jdoc 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c55cb2cd6e9fb7c413955cb27466ea7166210666
-  data.tar.gz: 4dd21023b7af214e1eb448d3bd3410e00e4a0e36
+  metadata.gz: 3037f3d705868d91ab1a9760532a0c94b40443a9
+  data.tar.gz: 3902451a12fa080192ad162f505937ccaaade5ec
 SHA512:
-  metadata.gz: cd723d33c3bfeff779db5a8725829c4895d38a63c7ea6ee787a6c31d6879e95c0e41577975115f2c8688f874325b9f6d353777e43451d6375e275f369654f0cb
-  data.tar.gz: daba310565e86e8d309582676311b396a76bccbf48b9e4c932b0d616107db36c2d92a66ce62c26df4f1ad4bd00726f526f8fcba9ce7f188c8a07739fb568f1b6
+  metadata.gz: b013094bfbc4221fd7eb72d5ff4ef01ab6015dd08bd026702b3a32024dc65de55df2076cbb32854d7eace2958acc4538d9134b7286f4bf726a52bc1bb4cfcb9a
+  data.tar.gz: ea026e0adb173194b64df59fbfb60a47db6483f47f3c4a60f434192f821dc4611b90a63bac0ab1ef4221b614478eb610d1f394fafb2e6110dda30f7c1888042e

data/CHANGELOG.md

@@ -1,3 +1,6 @@
+## 0.2.1
+* Support multipart/form-data
+
 ## 0.2.0
 * Show schema description on docs if exists
 

data/example-api-documentation.md

@@ -1,11 +1,13 @@
 # Example API
 A schema for a small example API.
+
 * [App](#app)
  * [POST /apps](#post-apps)
  * [DELETE /apps/:id](#delete-appsid)
  * [GET /apps/:id](#get-appsid)
  * [GET /apps](#get-apps)
  * [PATCH /apps/:id](#patch-appsid)
+ * [POST /apps/:id/files](#post-appsidfiles)
 * [Recipe](#recipe)
  * [GET /recipes](#get-recipes)
 * [User](#user)
@@ -190,6 +192,41 @@ Content-Type: application/json
 }
 ```
 
-----BoundaryX--
+### POST /apps/:id/files
+Upload an attachment file for an app
+
+```
+POST /apps/:id/files HTTP/1.1
+Content-Type: multipart/form-data; boundary=---BoundaryX
+Host: api.example.com
+
+-----BoundaryX
+Content-Disposition: form-data; name="[file]"
+
+... contents of file ...
+
+```
+
+```
+HTTP/1.1 201
+Content-Type: application/json
+
+{
+  "id": "01234567-89ab-cdef-0123-456789abcdef",
+  "name": "example",
+  "private": false,
+  "deleted_at": null,
+  "user_ids": [
+    1
+  ],
+  "users": [
+    {
+      "name": "alice"
+    }
+  ]
+}
+```
+
 ## Recipe
 
 

data/jdoc.gemspec

@@ -19,6 +19,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "activesupport"
   spec.add_dependency "erubis"
   spec.add_dependency "json_schema"
+  spec.add_dependency "rack"
   spec.add_dependency "redcarpet"
   spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "pry"

data/lib/jdoc.rb

@@ -4,10 +4,12 @@ require "cgi"
 require "erubis"
 require "json_schema"
 require "redcarpet"
+require "rack"
 require "uri"
 
 require "jdoc/generator"
 require "jdoc/link"
+require 'jdoc/request/multipart'
 require "jdoc/property"
 require "jdoc/resource"
 require "jdoc/schema"

data/lib/jdoc/link.rb

@@ -62,6 +62,14 @@ module Jdoc
       end
     end
 
+    # @return [String] request content type
+    # @note default value is "application/json"
+    def content_type
+      type = @raw_link.enc_type
+      type += "; #{Request::Multipart.boundary}" if content_type_multipart?
+      type
+    end
+
     # Adds query string if a link has a schema property and method is GET
     # @return [String, nil] A query string prefixed with `?` only to GET request
     # @example
@@ -74,7 +82,25 @@ module Jdoc
 
     # @return [String, nil] Example request body in JSON format
     def request_body
-      JSON.pretty_generate(request_parameters) + "\n"
+      body = case
+      when content_type_multipart?
+        request_body_in_multipart
+      when content_type_json?
+        request_body_in_json
+      else
+        ""
+      end
+      body + "\n"
+    end
+
+    # @return [true, false] True if encType of request is multipart/form-data
+    def content_type_multipart?
+      Rack::Mime.match?(@raw_link.enc_type, "multipart/form-data")
+    end
+
+    # @return [true, false] True if encType of request is multipart/form-data
+    def content_type_json?
+      Rack::Mime.match?(@raw_link.enc_type, "application/json")
     end
 
     # @return [Hash] Example request parameters for this endpoint
@@ -138,6 +164,16 @@ module Jdoc
       ResponseGenerator.call(response_schema.properties)
     end
 
+    # @return [String, nil] Example request body in Multipart
+    def request_body_in_multipart
+      Request::Multipart.new(request_parameters).dump
+    end
+
+    # @return [String, nil] Example request body in JSON format
+    def request_body_in_json
+      JSON.pretty_generate(request_parameters)
+    end
+
     # @return [Fixnum] Order score, used to sort links by preferred method order
     def method_order_score
       case method

data/lib/jdoc/request/multipart.rb

@@ -0,0 +1,43 @@
+module Jdoc
+  module Request
+    class Multipart
+      MULTIPART_BOUNDARY = "---BoundaryX"
+
+      # @return [String] returns boundary parameter for multipart content-type
+      def self.boundary
+        "boundary=#{MULTIPART_BOUNDARY}"
+      end
+
+      # @param params [Hash] request parameters
+      def initialize(params)
+        @params = params
+      end
+
+      # @return [String] request body of multipart/form-data request.
+      # @example
+      #   -----BoundaryX
+      #   Content-Disposition: form-data; name="file"
+      #
+      #   ... contents of file ...
+      #   -----BoundaryX--
+      def dump
+        contents = Rack::Multipart::Generator.new(@params, false).dump.map do |name, content|
+          content_part(content, name)
+        end.join
+        "#{contents}\r--#{MULTIPART_BOUNDARY}--\r"
+      end
+
+      private
+
+      # return [String] content part of multipart/form-data request
+      def content_part(content, name)
+<<-EOF
+--#{MULTIPART_BOUNDARY}\r
+Content-Disposition: form-data; name="#{name}"\r
+\r
+#{content}
+EOF
+      end
+    end
+  end
+end

data/lib/jdoc/version.rb

@@ -1,3 +1,3 @@
 module Jdoc
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/spec/fixtures/schema.yml

@@ -40,6 +40,11 @@ definitions:
         items:
           type: integer
           example: 1
+      file:
+        description: an attachment of app
+        example: '... contents of file ...'
+        readOnly: false
+        type: string
     links:
     - description: Create a new app.
       href: "/apps"
@@ -78,6 +83,18 @@ definitions:
         type:
         - object
       title: Update
+    - description: Upload an attachment file for an app
+      href: "/apps/{(%23%2Fdefinitions%2Fapp%2Fdefinitions%2Fid)}/files"
+      method: POST
+      rel: create
+      encType: multipart/form-data
+      schema:
+        properties:
+          file:
+            "$ref": "#/definitions/app/definitions/file"
+        type:
+        - object
+      title: Create
     properties:
       id:
         "$ref": "#/definitions/app/definitions/id"

data/template.md.erb

@@ -28,7 +28,7 @@
 
 ```
 <%= link.method %> <%= link.path %><%= link.query_string %> HTTP/1.1
-<%= "Content-Type: application/json\n" if link.has_request_body? -%>
+<%= "Content-Type: #{link.content_type}\n" if link.has_request_body? -%>
 Host: <%= schema.host_with_port %>
 <%= "\n" + link.request_body if link.has_request_body? -%>
 ```

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jdoc
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Ryo Nakamura
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-01 00:00:00.000000000 Z
+date: 2014-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: redcarpet
   requirement: !ruby/object:Gem::Requirement
@@ -143,6 +157,7 @@ files:
 - lib/jdoc/generator.rb
 - lib/jdoc/link.rb
 - lib/jdoc/property.rb
+- lib/jdoc/request/multipart.rb
 - lib/jdoc/resource.rb
 - lib/jdoc/schema.rb
 - lib/jdoc/version.rb