jdoc 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3037f3d705868d91ab1a9760532a0c94b40443a9
-  data.tar.gz: 3902451a12fa080192ad162f505937ccaaade5ec
+  metadata.gz: 882fb1ca942392f3f55bac3f59a40cb5b5fe6305
+  data.tar.gz: 273cefe1904b0e628430ff94716ccd8a7642ff0b
 SHA512:
-  metadata.gz: b013094bfbc4221fd7eb72d5ff4ef01ab6015dd08bd026702b3a32024dc65de55df2076cbb32854d7eace2958acc4538d9134b7286f4bf726a52bc1bb4cfcb9a
-  data.tar.gz: ea026e0adb173194b64df59fbfb60a47db6483f47f3c4a60f434192f821dc4611b90a63bac0ab1ef4221b614478eb610d1f394fafb2e6110dda30f7c1888042e
+  metadata.gz: 1c3bf5c1527a6a9e9c88e2fd16cc0c9c6c1d6504c920fb6346d783489b1ee89750e77ec8168ba93a9c38a74f87a9dcca5de7d00f3e347127bc1312c5d51e583a
+  data.tar.gz: c377a2e9e92a1252d338b671161c7cb8be598dd849920972262e6dea7685470db14e0cbf3478e90353c92699996f01c28dfa7a89d8cd34cf52b03c2d1362bea7

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.3.0
+* Change example response status and body to PUT & DELETE requests
+* Improve request path example by resolving variable in path
+
 ## 0.2.1
 * Support multipart/form-data
 

data/example-api-documentation.md

@@ -56,7 +56,6 @@ Host: api.example.com
 ```
 HTTP/1.1 201
 Content-Type: application/json
-
 {
   "id": "01234567-89ab-cdef-0123-456789abcdef",
   "name": "example",
@@ -77,42 +76,25 @@ Content-Type: application/json
 Delete an existing app.
 
 ```
-DELETE /apps/:id HTTP/1.1
+DELETE /apps/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
 Host: api.example.com
 ```
 
 ```
-HTTP/1.1 200
-Content-Type: application/json
-
-{
-  "id": "01234567-89ab-cdef-0123-456789abcdef",
-  "name": "example",
-  "private": false,
-  "deleted_at": null,
-  "user_ids": [
-    1
-  ],
-  "users": [
-    {
-      "name": "alice"
-    }
-  ]
-}
+HTTP/1.1 204
 ```
 
 ### GET /apps/:id
 Info for existing app.
 
 ```
-GET /apps/:id HTTP/1.1
+GET /apps/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
 Host: api.example.com
 ```
 
 ```
 HTTP/1.1 200
 Content-Type: application/json
-
 {
   "id": "01234567-89ab-cdef-0123-456789abcdef",
   "name": "example",
@@ -140,7 +122,6 @@ Host: api.example.com
 ```
 HTTP/1.1 200
 Content-Type: application/json
-
 [
   {
     "id": "01234567-89ab-cdef-0123-456789abcdef",
@@ -163,7 +144,7 @@ Content-Type: application/json
 Update an existing app.
 
 ```
-PATCH /apps/:id HTTP/1.1
+PATCH /apps/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
 Content-Type: application/json
 Host: api.example.com
 
@@ -175,7 +156,6 @@ Host: api.example.com
 ```
 HTTP/1.1 200
 Content-Type: application/json
-
 {
   "id": "01234567-89ab-cdef-0123-456789abcdef",
   "name": "example",
@@ -196,7 +176,7 @@ Content-Type: application/json
 Upload an attachment file for an app
 
 ```
-POST /apps/:id/files HTTP/1.1
+POST /apps/01234567-89ab-cdef-0123-456789abcdef/files HTTP/1.1
 Content-Type: multipart/form-data; boundary=---BoundaryX
 Host: api.example.com
 
@@ -210,7 +190,6 @@ Content-Disposition: form-data; name="[file]"
 ```
 HTTP/1.1 201
 Content-Type: application/json
-
 {
   "id": "01234567-89ab-cdef-0123-456789abcdef",
   "name": "example",
@@ -247,7 +226,6 @@ Host: api.example.com
 ```
 HTTP/1.1 200
 Content-Type: application/json
-
 [
   {
     "name": "Sushi",

data/lib/jdoc/link.rb

@@ -57,11 +57,20 @@ module Jdoc
     # @example
     #   link.path #=> "GET /apps/:id"
     def path
-      @path ||= @raw_link.href.gsub(/{(.+?)}/) do |matched|
+      @path ||= @raw_link.href.gsub(/{(.+?)}/) do
         ":" + CGI.unescape($1).gsub(/[()\s]/, "").split("/").last
       end
     end
 
+    # @returns [String] Path with embedded example variable
+    # @example
+    #   link.example_path #=> "GET /apps/1"
+    def example_path
+      @example_path ||= @raw_link.href.gsub(/{\((.+?)\)}/) do
+        JsonPointer.evaluate(root_schema.data, CGI.unescape($1))["example"]
+      end
+    end
+
     # @return [String] request content type
     # @note default value is "application/json"
     def content_type
@@ -119,6 +128,12 @@ module Jdoc
       ["PATCH", "POST", "PUT"].include?(method)
     end
 
+    # We have a policy that we should not return response body to PUT and DELETE requests.
+    # @return [true, false] True if this endpoint must have response body
+    def has_response_body?
+      !["PUT", "DELETE"].include?(method)
+    end
+
     # @return [String] JSON response body generated from example properties
     def response_body
       object = has_list_data? ? [response_hash] : response_hash
@@ -127,7 +142,14 @@ module Jdoc
 
     # @return [Fixnum] Preferred respone status code for this endpoint
     def response_status
-      method == "POST" ? 201 : 200
+      case method
+      when "POST"
+        201
+      when "PUT", "DELETE"
+        204
+      else
+        200
+      end
     end
 
     # @return [JsonSchema::Schema] Response schema for this link
@@ -148,6 +170,17 @@ module Jdoc
 
     private
 
+    # @return [JsonSchema::Schema] Root schema object this link is associated to
+    def root_schema
+      @root ||= begin
+        schema = @raw_link
+        while schema.parent
+          schema = schema.parent
+        end
+        schema
+      end
+    end
+
     # @return [true, false] True if a given link has a schema property
     def has_schema_in_link?
       !!@raw_link.schema

data/lib/jdoc/version.rb

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

data/template.md.erb

@@ -27,7 +27,7 @@
 <%= link.description %>
 
 ```
-<%= link.method %> <%= link.path %><%= link.query_string %> HTTP/1.1
+<%= link.method %> <%= link.example_path %><%= link.query_string %> HTTP/1.1
 <%= "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? -%>
@@ -35,9 +35,8 @@ Host: <%= schema.host_with_port %>
 
 ```
 HTTP/1.1 <%= link.response_status %>
-Content-Type: application/json
-
-<%= link.response_body %>
+<%= "Content-Type: application/json" if link.has_response_body? -%>
+<%= "\n#{link.response_body}\n" if link.has_response_body? -%>
 ```
 
 <% end %>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jdoc
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Ryo Nakamura
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-04 00:00:00.000000000 Z
+date: 2014-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport