class Jdoc::Link
Public Class Methods
@param link [JsonSchema::Schema::Link]
# File lib/jdoc/link.rb, line 4 def initialize(link) @raw_link = link end
Public Instance Methods
Responds to .sort method @return [Fixnum]
# File lib/jdoc/link.rb, line 17 def <=>(schema) sort_key <=> schema.sort_key end
@return [String] Href anchor for putting link in ToC @example
link.anchor #=> "#get-apps"
# File lib/jdoc/link.rb, line 37 def anchor "#" + endpoint.gsub(" ", "-").gsub(/[:\/]/, "").downcase end
@return [String] request content type @note default value is “application/json”
# File lib/jdoc/link.rb, line 83 def content_type type = @raw_link.enc_type type += "; #{Request::Multipart.boundary}" if content_type_multipart? type end
@return [true, false] True if encType of request is multipart/form-data
# File lib/jdoc/link.rb, line 118 def content_type_json? Rack::Mime.match?(@raw_link.enc_type, "application/json") end
@return [true, false] True if encType of request is multipart/form-data
# File lib/jdoc/link.rb, line 113 def content_type_multipart? Rack::Mime.match?(@raw_link.enc_type, "multipart/form-data") end
@return [String] Description for this endpoint, defined in description property @example
link.description #=> "List existing apps."
# File lib/jdoc/link.rb, line 30 def description @raw_link.description end
@return [String] method + path @example
link.endpoint #=> "GET /apps"
# File lib/jdoc/link.rb, line 11 def endpoint "#{method} #{path}" end
@returns [String] Path with embedded example variable @raise [Rack::Spec::Mock::ExampleNotFound] @example
link.example_path #=> "/apps/1"
# File lib/jdoc/link.rb, line 69 def example_path @example_path ||= @raw_link.href.gsub(/{\((.+?)\)}/) do pointer = CGI.unescape($1) value = JsonPointer.evaluate(root_schema.data, pointer) if value && value["example"] value["example"] else raise ExampleNotFound, "No example found for #{pointer}" end end end
@return [true, false] True if this endpoint must have request body
# File lib/jdoc/link.rb, line 147 def has_request_body? ["PATCH", "POST", "PUT"].include?(method) && !request_parameters.empty? 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
# File lib/jdoc/link.rb, line 153 def has_response_body? @raw_link.media_type != "null" end
@return [String] Markdown styled link text for endpoint @example
link.hyperlink #=> "[GET /apps](#get-apps)"
# File lib/jdoc/link.rb, line 44 def hyperlink "[#{endpoint}](#{anchor})" end
@return [String] Upper cased HTTP request method name @example
link.method #=> "GET"
# File lib/jdoc/link.rb, line 51 def method @method ||= @raw_link.method.to_s.upcase end
@return [String] Request
path name, defined at href property @note URI Template is replaced with placeholder @example
link.path #=> "/apps/:id"
# File lib/jdoc/link.rb, line 59 def path @path ||= @raw_link.href.gsub(/{(.+?)}/) do ":" + CGI.unescape($1).gsub(/[()\s]/, "").split("/").last end 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
link.query_string #=> "?type=Recipe"
# File lib/jdoc/link.rb, line 93 def query_string if method == "GET" && !request_parameters.empty? "?#{request_parameters.to_query}" end end
@return [String, nil] Example request body in JSON format
# File lib/jdoc/link.rb, line 100 def request_body body = case when content_type_multipart? request_body_in_multipart when content_type_json? request_body_in_json else "" end body + "\n" end
@return [Hash] Example request parameters for this endpoint
# File lib/jdoc/link.rb, line 123 def request_parameters @request_parameters ||= begin if request_schema RequestGenerator.call(request_schema.properties) else {} end end end
@return [Array<Jdoc::Property>] Properties defined in this link's schema property.
# File lib/jdoc/link.rb, line 134 def request_properties @request_properties ||= begin if request_schema request_schema.properties.map do |name, schema| Property.new(name: name, schema: schema) end else [] end end end
@return [JsonSchema::Schema] Request
schema for this link
# File lib/jdoc/link.rb, line 193 def request_schema @raw_link.schema end
@return [Json::Link::Resource] @note Resource
means each property of top-level properties in this context
# File lib/jdoc/link.rb, line 199 def resource @resource ||= Resource.new(response_schema) end
@return [String] JSON response body generated from example properties
# File lib/jdoc/link.rb, line 158 def response_body object = has_list_data? ? [response_hash] : response_hash JSON.pretty_generate(object) end
@return [String] Preferred respone reason phrase for this endpoint
# File lib/jdoc/link.rb, line 176 def response_reason_phrase case when method == "POST" "Created" when has_response_body? "OK" else "No Content" end end
@return [JsonSchema::Schema] Response schema for this link
# File lib/jdoc/link.rb, line 188 def response_schema @raw_link.target_schema || @raw_link.parent end
@return [Fixnum] Preferred respone status code for this endpoint
# File lib/jdoc/link.rb, line 164 def response_status case when method == "POST" 201 when has_response_body? 200 else 204 end end
For #<=> method @return [String]
# File lib/jdoc/link.rb, line 23 def sort_key "#{path} #{method_order_score}" end
Private Instance Methods
@return [true, false] True if response is intended to be list data
# File lib/jdoc/link.rb, line 217 def has_list_data? @raw_link.rel == "instances" end
@return [Fixnum] Order score, used to sort links by preferred method order
# File lib/jdoc/link.rb, line 238 def method_order_score case method when "GET" 1 when "POST" 2 when "PUT" 3 when "PATCH" 4 when "DELETE" 5 else 6 end end
@return [String, nil] Example request body in JSON format
# File lib/jdoc/link.rb, line 233 def request_body_in_json JSON.pretty_generate(request_parameters) end
@return [String, nil] Example request body in Multipart
# File lib/jdoc/link.rb, line 228 def request_body_in_multipart Request::Multipart.new(request_parameters).dump end
@return [Hash] @raise [Rack::Spec::Mock::ExampleNotFound]
# File lib/jdoc/link.rb, line 223 def response_hash ResponseGenerator.call(response_schema.properties) end
@return [JsonSchema::Schema] Root schema object this link is associated to
# File lib/jdoc/link.rb, line 206 def root_schema @root ||= begin schema = @raw_link while schema.parent schema = schema.parent end schema end end