Rack::JsonSchema

JSON Schema based Rack middlewares.

Rack::JsonSchema::RequestValidation
Rack::JsonSchema::ResponseValidation
Rack::JsonSchema::Mock
Rack::JsonSchema::ErrorHandler
Rack::JsonSchema::Docs
Rack::JsonSchema::SchemaProvider
specup

Usage

str = File.read("schema.json")
schema = JSON.parse(str)

use Rack::JsonSchema::Docs, schema: schema
use Rack::JsonSchema::SchemaProvider, schema: schema
use Rack::JsonSchema::ErrorHandler
use Rack::JsonSchema::RequestValidation, schema: schema
use Rack::JsonSchema::ResponseValidation, schema: schema if ENV["RACK_ENV"] == "test"
use Rack::JsonSchema::Mock, schema: schema if ENV["RACK_ENV"] == "mock"

Rack::JsonSchema::RequestValidation

Validates request and raises errors below. The rack will automatically look into the corresponding hypermedia definitions.

Rack::JsonSchema::RequestValidation::InvalidContentType
Rack::JsonSchema::RequestValidation::InvalidJson
Rack::JsonSchema::RequestValidation::InvalidParameter
Rack::JsonSchema::RequestValidation::LinkNotFound

$ curl http://localhost:8080/users
{
  "id": "link_not_found",
  "message": "Not found"
}

$ curl http://localhost:8080/apps -H "Content-Type: application/json" -d "invalid-json"
{
  "id": "invalid_json",
  "message": "Request body wasn't valid JSON"
}

$ curl http://localhost:8080/apps -H "Content-Type: text/plain" -d "{}"
{
  "id": "invalid_content_type",
  "message": "Invalid content type"
}

$ curl http://localhost:8080/apps -H "Content-Type: application/json" -d '{"name":"x"}'
{
  "id": "invalid_parameter",
  "message": "Invalid request.\n#/name: failed schema #/definitions/app/links/0/schema/properties/name: Expected string to match pattern \"/^[a-z][a-z0-9-]{3,50}$/\", value was: x."
}

Rack::JsonSchema::ResponseValidation

Validates response and raises errors below.

Rack::JsonSchema::ResponseValidation::InvalidResponseContentType
Rack::JsonSchema::ResponseValidation::InvalidResponseType

$ curl http://localhost:8080/apps
{
  "id": "invalid_response_content_type",
  "message": "Response Content-Type wasn't for JSON"
}

$ curl http://localhost:8080/apps
{
  "id": "invalid_response_type",
  "message": "#: failed schema #/definitions/app: Expected data to be of type \"object\"; value was: [\"message\", \"dummy\"]."
}

Rack::JsonSchema::Mock

Generates dummy response from JSON schema.

$ curl http://localhost:8080/apps
[
  {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  }
]

$ curl http://localhost:8080/apps/01234567-89ab-cdef-0123-456789abcdef
{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example"
}

$ curl http://localhost:8080/apps/1 -d '{"name":"example"}'
{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example"
}

$ curl http://localhost:8080/recipes
{
  "id": "example_not_found",
  "message": "No example found for #/definitions/recipe/id"
}

Rack::JsonSchema::ErrorHandler

Returns appropriate error response including following properties when RequestValidation raises error.

message: Human readable message
id: Error type identifier listed below
example_not_found
invalid_content_type
invalid_json
invalid_parameter
invalid_response_content_type
invalid_response_type
link_not_found

Here is a tree of all possible errors defined in Rack::JsonSchema.

StandardError
|
Rack::JsonSchema::Error
|
|--Rack::JsonSchema::Mock::Error
|  |
|  `--Rack::JsonSchema::Mock::ExampleNotFound
|
|--Rack::JsonSchema::RequestValidation::Error
|  |
|  |--Rack::JsonSchema::RequestValidation::InvalidContentType
|  |
|  |--Rack::JsonSchema::RequestValidation::InvalidJson
|  |
|  |--Rack::JsonSchema::RequestValidation::InvalidParameter
|  |
|  `--Rack::JsonSchema::RequestValidation::LinkNotFound
|
`--Rack::JsonSchema::ResponseValidation::Error
   |
   |--Rack::JsonSchema::ResponseValidation::InvalidResponseContentType
   |
   `--Rack::JsonSchema::ResponseValidation::InvalidResponseType

Rack::JsonSchema::Docs

Returns API documentation as text/html (GET /docs) or text/plain (GET /docs.md).

You can give path option to change default path: GET /docs
API documentation is powered by jdoc gem
This middleware is also bundled in the specup executable command

Rack::JsonSchema::SchemaProvider

Serves JSON Schema at GET /schema.

You can give path option to change default path: GET /schema
This middleware is also bundled in the specup executable command

specup

specup executable command is bundled to rackup handy mock API server. It validates requests, and returns dummy response, also returns auto-generated API documentation at GET /docs, and JSON Schema itself at GET /schema.

$ specup schema.json
[2014-06-06 23:01:35] INFO  WEBrick 1.3.1
[2014-06-06 23:01:35] INFO  ruby 2.0.0 (2013-06-27) [x86_64-darwin12.5.0]
[2014-06-06 23:01:35] INFO  WEBrick::HTTPServer#start: pid=24303 port=8080

$ curl :8080/docs
# Example API
* [App](#app)
 * [GET /apps](#get-apps)
 * [POST /apps](#post-apps)
 * [GET /apps/:id](#get-appsid)
 * [PATCH /apps/:id](#patch-appsid)
 * [DELETE /apps/:id](#delete-appsid)
* [Recipe](#recipe)
 * [GET /recipes](#get-recipes)
...

$ curl :8080/schema
HTTP/1.1 200 OK
{
  "$schema": "http://json-schema.org/draft-04/hyper-schema",
  "definitions": {
    "app": {
      "$schema": "http://json-schema.org/draft-04/hyper-schema",
      "description": "An app is a program to be deployed.",
      "id": "schemata/app",
      "title": "App",
      ...
    }
  }
}

$ curl :8080/apps/1
[
  {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  }
]

$ curl :8080/apps -H "Content-Type: application/json" -d '{"name":1}'
{
  "id": "invalid_parameter",
  "message": "Invalid request.\n#/name: failed schema #/definitions/app/links/0/schema/properties/name: Expected data to be of type \"string\"; value was: 1."
}

rack-spec

Development

Runtime