link.rb in jdoc-0.3.0

- old
+ new

@@ -55,15 +55,24 @@
     # @return [String] Request path name, defined at href property
     # @note URI Template is replaced with placeholder
     # @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
       type = @raw_link.enc_type
       type += "; #{Request::Multipart.boundary}" if content_type_multipart?
@@ -117,19 +126,32 @@
     # @return [true, false] True if this endpoint must have request body
     def has_request_body?
       ["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
       JSON.pretty_generate(object)
     end
 
     # @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
     def response_schema
       @raw_link.target_schema || @raw_link.parent
@@ -145,9 +167,20 @@
     def resource
       @resource ||= Resource.new(response_schema)
     end
 
     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
     end