class Jdoc::Link

Public Class Methods

new(link) click to toggle source

@param link [JsonSchema::Schema::Link]

# File lib/jdoc/link.rb, line 4
def initialize(link)
  @raw_link = link
end

Public Instance Methods

<=>(schema) click to toggle source

Responds to .sort method @return [Fixnum]

# File lib/jdoc/link.rb, line 17
def <=>(schema)
  sort_key <=> schema.sort_key
end
anchor() click to toggle source

@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
content_type() click to toggle source

@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
content_type_json?() click to toggle source

@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
content_type_multipart?() click to toggle source

@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
description() click to toggle source

@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
endpoint() click to toggle source

@return [String] method + path @example

link.endpoint #=> "GET /apps"
# File lib/jdoc/link.rb, line 11
def endpoint
  "#{method} #{path}"
end
example_path() click to toggle source

@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
has_request_body?() click to toggle source

@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
has_response_body?() click to toggle source

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
method() click to toggle source

@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
path() click to toggle source

@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
query_string() click to toggle source

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
request_body() click to toggle source

@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
request_parameters() click to toggle source

@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
request_properties() click to toggle source

@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
request_schema() click to toggle source

@return [JsonSchema::Schema] Request schema for this link

# File lib/jdoc/link.rb, line 193
def request_schema
  @raw_link.schema
end
resource() click to toggle source

@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
response_body() click to toggle source

@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
response_reason_phrase() click to toggle source

@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
response_schema() click to toggle source

@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
response_status() click to toggle source

@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
sort_key() click to toggle source

For #<=> method @return [String]

# File lib/jdoc/link.rb, line 23
def sort_key
  "#{path} #{method_order_score}"
end

Private Instance Methods

has_list_data?() click to toggle source

@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
method_order_score() click to toggle source

@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
request_body_in_json() click to toggle source

@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
request_body_in_multipart() click to toggle source

@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
response_hash() click to toggle source

@return [Hash] @raise [Rack::Spec::Mock::ExampleNotFound]

# File lib/jdoc/link.rb, line 223
def response_hash
  ResponseGenerator.call(response_schema.properties)
end
root_schema() click to toggle source

@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