rack-json_schema 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 52921d3192984f9d393b0501b2d4953b5bb3be36
+  data.tar.gz: 635f81c7e1ac5b97893fca271f6326aefe2d03d4
+SHA512:
+  metadata.gz: 0c0a01694af3f7ab3df6c1579c6f5e755aba351abf08c3e8f8fa1490e87bcdef8a99ee25bdee239dbc26f9881c44a70b958ff04cfe74bdd37df137153f4774ac
+  data.tar.gz: d746e6349cf8c99755502182ae338c75ef13f1eba04b8bcd287778aabe802739b1137ac91f70219504ec28c485b0a70de33a9747eb7977ca133175861a7ead8f

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+## 1.0.0
+* Rename: rack-spec -> rack-json_schema
+
+## 0.1.8
+* Add Rack::JsonSchema::Docs
+
+## 0.1.7
+* Reveal `Rack::JsonSchema::Schema#links`
+
+## 0.1.6
+* Support YAML schema at `specup`
+
+## 0.1.5
+* Add `specup` executable
+
+## 0.1.4
+* Add Rack::JsonSchema::Mock
+* Prettify response JSON
+
+## v0.1.3
+* Array response support of Rack::JsonSchema::ResponseValidation
+
+## v0.1.2
+* Change Content-Type validation policy
+* Add Rack::JsonSchema::ResponseValidation
+
+## v0.1.1
+* Add ErrorHandler rack middleware for building error response
+
+## v0.1.0
+* Rebuilt entire code based on JSON schema
+
+## v0.0.5
+* Change RESTful resource API (#get, #post, #put, and #delete)
+
+## v0.0.4
+* Add Rack::JsonSchema::Restful, strongly conventional RESTful API Provider
+
+## v0.0.3
+* Add a new constraint: required
+* More DRY way for validator definition
+
+## v0.0.2
+* Change key name: queryParameters -> parameters
+* Add a new constraint: only
+* Add a new constraint: minimumLength
+* Add a new constraint: maxinumLength
+
+## v0.0.1
+* Add a new constraint: type
+* Add a new constraint: minimum
+* Add a new constraint: maxinum

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# JsonSchemaify your gem's dependencies in rack-spec.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Ryo Nakamura
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,200 @@
+# Rack::JsonSchema
+[JSON Schema](http://json-schema.org/) based Rack middlewares.
+
+## Usage
+```ruby
+str = File.read("schema.json")
+schema = JSON.parse(str)
+
+use Rack::JsonSchema::Docs, 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.
+
+* Rack::JsonSchema::RequestValidation::InvalidContentType
+* Rack::JsonSchema::RequestValidation::InvalidJson
+* Rack::JsonSchema::RequestValidation::InvalidParameter
+* Rack::JsonSchema::RequestValidation::LinkNotFound
+
+```sh
+$ curl http://localhost:9292/users
+{
+  "id": "link_not_found",
+  "message": "Not found"
+}
+
+$ curl http://localhost:9292/apps -H "Content-Type: application/json" -d "invalid-json"
+{
+  "id": "invalid_json",
+  "message": "Request body wasn't valid JSON"
+}
+
+$ curl http://localhost:9292/apps -H "Content-Type: text/plain" -d "{}"
+{
+  "id": "invalid_content_type",
+  "message": "Invalid content type"
+}
+
+$ curl http://localhost:9292/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 request and raises errors below.
+
+* Rack::JsonSchema::RequestValidation::InvalidResponseContentType
+* Rack::JsonSchema::RequestValidation::InvalidResponseType
+
+```sh
+$ curl http://localhost:9292/apps
+{
+  "id": "invalid_response_content_type",
+  "message": "Response Content-Type wasn't for JSON"
+}
+
+$ curl http://localhost:9292/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.
+
+```sh
+$ curl http://localhost:9292/apps/1
+[
+  {
+    "id": "01234567-89ab-cdef-0123-456789abcdef",
+    "name": "example"
+  }
+]
+
+$ curl http://localhost:9292/apps/01234567-89ab-cdef-0123-456789abcdef
+{
+  "id": "01234567-89ab-cdef-0123-456789abcdef",
+  "name": "example"
+}
+
+$ curl http://localhost:9292/apps/1 -d '{"name":"example"}'
+{
+  "id": "01234567-89ab-cdef-0123-456789abcdef",
+  "name": "example"
+}
+
+$ curl http://localhost:9292/recipes
+{
+  "id": "example_not_found",
+  "message": "No example found for #/definitions/recipe/id"
+}
+```
+
+Note: `specup` executable command is bundled to rackup dummy API server.
+
+```sh
+$ 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
+```
+
+### 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 a text/plain content, rendered in GitHub flavored Markdown.
+
+* You can give `path` option to change default path: `GET /docs`
+* API documentation is powered by [jdoc](https://github.com/r7kamura/jdoc) gem
+* This middleware is also bundled in the `specup` executable command
+
+```sh
+$ 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 -i
+HTTP/1.1 200 OK
+Content-Type: text/plain; charset=utf-8
+Server: WEBrick/1.3.1 (Ruby/2.1.1/2014-02-24)
+Date: Sat, 07 Jun 2014 19:58:04 GMT
+Content-Length: 2175
+Connection: Keep-Alive
+
+# 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)
+
+## App
+An app is a program to be deployed.
+
+### Properties
+* id - unique identifier of app
+ * Example: `01234567-89ab-cdef-0123-456789abcdef`
+ * Type: string
+ * Format: uuid
+ * ReadOnly: true
+* name - unique name of app
+ * Example: `example`
+ * Type: string
+ * Patern: `(?-mix:^[a-z][a-z0-9-]{3,50}$)`
+
+### GET /apps
+List existing apps.
+
+...
+```

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/specup

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
+require "rack"
+require "rack/json_schema"
+require "yaml"
+
+begin
+  path = ARGV.shift or raise
+  str = File.read(path)
+rescue
+  puts "Usage: #{$0} schema.json [rack options]"
+  exit
+end
+
+case File.extname(path)
+when ".yml", ".yaml"
+  schema = YAML.load(str)
+else
+  schema = MultiJson.decode(str)
+end
+
+app = Rack::Builder.new do
+  use Rack::JsonSchema::Docs, schema: schema
+  use Rack::JsonSchema::ErrorHandler
+  use Rack::JsonSchema::Mock, schema: schema
+  run ->(env) { [404, {}, ["Not found"]] }
+end
+
+options = Rack::Server::Options.new.parse!(ARGV).merge(app: app)
+Rack::Server.start(options)

data/lib/rack-json_schema.rb

@@ -0,0 +1 @@
+require "rack/json_schema"

data/lib/rack/json_schema.rb

@@ -0,0 +1,15 @@
+require "jdoc"
+require "json"
+require "json_schema"
+require "multi_json"
+require "rack"
+
+require "rack/json_schema/base_request_handler"
+require "rack/json_schema/error"
+require "rack/json_schema/docs"
+require "rack/json_schema/error_handler"
+require "rack/json_schema/mock"
+require "rack/json_schema/request_validation"
+require "rack/json_schema/response_validation"
+require "rack/json_schema/schema"
+require "rack/json_schema/version"

data/lib/rack/json_schema/base_request_handler.rb

@@ -0,0 +1,64 @@
+module Rack
+  module JsonSchema
+    # Base class for providing some utility methods to handle Rack env and JSON Schema
+    class BaseRequestHandler
+      # Utility wrapper method
+      def self.call(**args)
+        new(**args).call
+      end
+
+      # @param env [Hash] Rack env
+      # @param schema [JsonSchema::Schema] Schema object
+      def initialize(env: nil, schema: nil)
+        @env = env
+        @schema = schema
+      end
+
+      private
+
+      # Treats env as a utility object to easily extract method and path
+      # @return [Rack::Request]
+      def request
+        @request ||= Rack::Request.new(@env)
+      end
+
+      # @return [String] HTTP request method
+      # @example
+      #   method #=> "GET"
+      def method
+        request.request_method
+      end
+
+      # @return [String] Request path
+      # @example
+      #   path #=> "/recipes"
+      def path
+        request.path_info
+      end
+
+      # @return [JsonSchema::Schema::Link, nil] Link for the current action
+      def link
+        if instance_variable_defined?(:@link)
+          @link
+        else
+          @link = @schema.link_for(method: method, path: path)
+        end
+      end
+
+      # @return [true, false] True if link is defined for the current action
+      def has_link_for_current_action?
+        !!link
+      end
+
+      # @return [JsonSchema::Schema] Schema for current link, specified by targetSchema or parent schema
+      def schema_for_current_link
+        link.target_schema || link.parent
+      end
+
+      # @return [true, false] True if response is intended to be list data
+      def has_list_data?
+        link.rel == "instances" && !link.target_schema
+      end
+    end
+  end
+end

data/lib/rack/json_schema/docs.rb

@@ -0,0 +1,38 @@
+module Rack
+  module JsonSchema
+    class Docs
+      DEFAULT_PATH = "/docs"
+
+      # Behaves as a rack-middleware
+      # @param app [Object] Rack application
+      # @param path [String, nil] URL path to return document (default: /docs)
+      # @param schema [Hash] Schema object written in JSON schema format
+      def initialize(app, path: nil, schema: nil)
+        @app = app
+        @path = path
+        @document = Jdoc::Generator.call(schema)
+      end
+
+      # Returns rendered document for document request
+      # @param env [Hash] Rack env
+      def call(env)
+        if env["REQUEST_METHOD"] == "GET" && env["PATH_INFO"] == path
+          [
+            200,
+            { "Content-Type" => "text/plain; charset=utf-8" },
+            [@document],
+          ]
+        else
+          @app.call(env)
+        end
+      end
+
+      private
+
+      # @return [String] Path to return document
+      def path
+        @path || DEFAULT_PATH
+      end
+    end
+  end
+end