rack-spec 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 277859642681598d0b7da69a7c16e6248ddb4793
-  data.tar.gz: 4fa89bf9a124ff8346192e7f4354e63f60f88285
+  metadata.gz: f9795c070d0186c9a6438b83e16f99d451efd2e0
+  data.tar.gz: 9bc28b54878df5ff26bea3d3db7f4162ccaa39c0
 SHA512:
-  metadata.gz: 5e76e95ba99636e4691bcc608eef9d69851b3d9ecc20a2378ee0eb0fb3cf82746b4a2ed68de87229aa9807aac0a10105d9125d08d92c36cc314af90e425fcf33
-  data.tar.gz: e16f969d4e18f0e61eb2162a9c5e9e9a164e1a40cee3cc6693008121325aa56431846d714fc30a0edafbcb9ca10860b84dd82fce1266abc40ef19f41d690f9e6
+  metadata.gz: ddea8433e0f5c03b399acd9e3e6d91c73d24ad8c56ed6a9ce0409b022d1683a1464123e337257f0e5baf5124331899475aed2498afbc199172124f2d99bc8b7a
+  data.tar.gz: b49bd48bd82e0387e64496cf9ac599b633937fa4bad9b5323607208eb66853dbfb096c47e904f883dd9d5c088ea05e06d41342d5a10a89afd49ae2d890606474

data/CHANGELOG.md

@@ -1,3 +1,6 @@
+## 0.1.8
+* Add Rack::Spec::Docs
+
 ## 0.1.7
 * Reveal `Rack::Spec::Schema#links`
 

data/README.md

@@ -6,6 +6,7 @@
 str = File.read("schema.json")
 schema = JSON.parse(str)
 
+use Rack::Spec::Docs, schema: schema
 use Rack::Spec::ErrorHandler
 use Rack::Spec::RequestValidation, schema: schema
 use Rack::Spec::ResponseValidation, schema: schema if ENV["RACK_ENV"] == "test"
@@ -146,3 +147,54 @@ Rack::Spec::Error
    |
    `--Rack::Spec::ResponseValidation::InvalidResponseType
 ```
+
+### Rack::Spec::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/bin/specup

@@ -20,6 +20,7 @@ else
 end
 
 app = Rack::Builder.new do
+  use Rack::Spec::Docs, schema: schema
   use Rack::Spec::ErrorHandler
   use Rack::Spec::Mock, schema: schema
   run ->(env) { [404, {}, ["Not found"]] }

data/lib/rack/spec.rb

@@ -1,3 +1,4 @@
+require "jdoc"
 require "json"
 require "json_schema"
 require "multi_json"
@@ -5,6 +6,7 @@ require "rack"
 
 require "rack/spec/base_request_handler"
 require "rack/spec/error"
+require "rack/spec/docs"
 require "rack/spec/error_handler"
 require "rack/spec/mock"
 require "rack/spec/request_validation"

data/lib/rack/spec/docs.rb

@@ -0,0 +1,38 @@
+module Rack
+  module Spec
+    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

data/lib/rack/spec/version.rb

@@ -1,5 +1,5 @@
 module Rack
   module Spec
-    VERSION = "0.1.7"
+    VERSION = "0.1.8"
   end
 end

data/rack-spec.gemspec

@@ -17,6 +17,7 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "jdoc", ">= 0.0.3"
   spec.add_dependency "json_schema"
   spec.add_dependency "multi_json"
   spec.add_dependency "rack"

data/spec/fixtures/schema.json

@@ -108,6 +108,7 @@
           "description": "unique identifier of recipe",
           "format": "uuid",
           "readOnly": true,
+          "example": 1,
           "type": [
             "string"
           ]

data/spec/rack/spec/docs_spec.rb

@@ -0,0 +1,93 @@
+require "spec_helper"
+
+describe Rack::Spec::Docs do
+  include Rack::Test::Methods
+
+  let(:app) do
+    local_docs_path = docs_path
+    local_schema = schema
+    Rack::Builder.app do
+      use Rack::Spec::Docs, path: local_docs_path, schema: local_schema
+      run ->(env) do
+        [
+          200,
+          {},
+          ["dummy"],
+        ]
+      end
+    end
+  end
+
+  let(:schema) do
+    str = File.read(schema_path)
+    JSON.parse(str)
+  end
+
+  let(:schema_path) do
+    File.expand_path("../../../fixtures/schema.json", __FILE__)
+  end
+
+  let(:docs_path) do
+    nil
+  end
+
+  let(:response) do
+    last_response
+  end
+
+  let(:env) do
+    {}
+  end
+
+  let(:params) do
+    {}
+  end
+
+  subject do
+    send(verb, path, params, env)
+    response.status
+  end
+
+  describe "#call" do
+    let(:verb) do
+      :get
+    end
+
+    context "without :path option" do
+      let(:path) do
+        "/docs"
+      end
+
+      it "generates API documentation and returns it to request to GET /docs" do
+        should == 200
+        response.body.should include("Example API")
+      end
+    end
+
+    context "with :path option" do
+      let(:docs_path) do
+        "/api_document"
+      end
+
+      let(:path) do
+        "/api_document"
+      end
+
+      it "responds to specified path" do
+        should == 200
+        response.body.should_not == "dummy"
+      end
+    end
+
+    context "without targeted request" do
+      let(:path) do
+        "/apps"
+      end
+
+      it "delegates request to inner app" do
+        should == 200
+        response.body.should == "dummy"
+      end
+    end
+  end
+end

data/spec/rack/spec/mock_spec.rb

@@ -102,6 +102,10 @@ describe Rack::Spec::Mock do
     end
 
     context "without example" do
+      before do
+        schema["definitions"]["recipe"]["definitions"]["id"].delete("example")
+      end
+
       let(:verb) do
         :get
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rack-spec
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - Ryo Nakamura
@@ -10,6 +10,20 @@ bindir: bin
 cert_chain: []
 date: 2014-06-07 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: jdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.3
 - !ruby/object:Gem::Dependency
   name: json_schema
   requirement: !ruby/object:Gem::Requirement
@@ -168,6 +182,7 @@ files:
 - lib/rack-spec.rb
 - lib/rack/spec.rb
 - lib/rack/spec/base_request_handler.rb
+- lib/rack/spec/docs.rb
 - lib/rack/spec/error.rb
 - lib/rack/spec/error_handler.rb
 - lib/rack/spec/mock.rb
@@ -177,6 +192,7 @@ files:
 - lib/rack/spec/version.rb
 - rack-spec.gemspec
 - spec/fixtures/schema.json
+- spec/rack/spec/docs_spec.rb
 - spec/rack/spec/mock_spec.rb
 - spec/rack/spec_spec.rb
 - spec/spec_helper.rb
@@ -206,6 +222,7 @@ specification_version: 4
 summary: JSON Schema based Rack middlewares
 test_files:
 - spec/fixtures/schema.json
+- spec/rack/spec/docs_spec.rb
 - spec/rack/spec/mock_spec.rb
 - spec/rack/spec_spec.rb
 - spec/spec_helper.rb