Class: Jdoc::Link

Inherits:
Object
  • Object
show all
Defined in:
lib/jdoc/link.rb

Defined Under Namespace

Classes: ExampleNotFound, RequestGenerator, ResponseGenerator

Instance Method Summary collapse

Constructor Details

#initialize(link) ⇒ Link

Returns a new instance of Link.

Parameters:

  • link (JsonSchema::Schema::Link) 


4
5
6
 
# File 'lib/jdoc/link.rb', line 4

def initialize(link)
  @raw_link = link
end

Instance Method Details

#<=>(schema) ⇒ Fixnum

Responds to .sort method

Returns:

  • (Fixnum) 


17
18
19
 
# File 'lib/jdoc/link.rb', line 17

def <=>(schema)
  sort_key <=> schema.sort_key
end

#anchor ⇒ String

Returns Href anchor for putting link in ToC.

Examples:

link.anchor #=> "#get-apps"

Returns:

  • (String) —

    Href anchor for putting link in ToC



37
38
39
 
# File 'lib/jdoc/link.rb', line 37

def anchor
  "#" + endpoint.gsub(" ", "-").gsub(/[:\/]/, "").downcase
end

#content_type ⇒ String

Note:

default value is “application/json”

Returns request content type.

Returns:

  • (String) —

    request content type



83
84
85
86
87
 
# 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? ⇒ true, false

Returns True if encType of request is multipart/form-data.

Returns:

  • (true, false) —

    True if encType of request is multipart/form-data



118
119
120
 
# File 'lib/jdoc/link.rb', line 118

def content_type_json?
  Rack::Mime.match?(@raw_link.enc_type, "application/json")
end

#content_type_multipart? ⇒ true, false

Returns True if encType of request is multipart/form-data.

Returns:

  • (true, false) —

    True if encType of request is multipart/form-data



113
114
115
 
# File 'lib/jdoc/link.rb', line 113

def content_type_multipart?
  Rack::Mime.match?(@raw_link.enc_type, "multipart/form-data")
end

#description ⇒ String

Returns Description for this endpoint, defined in description property.

Examples:

link.description #=> "List existing apps."

Returns:

  • (String) —

    Description for this endpoint, defined in description property



30
31
32
 
# File 'lib/jdoc/link.rb', line 30

def description
  @raw_link.description
end

#endpoint ⇒ String

Returns method + path.

Examples:

link.endpoint #=> "GET /apps"

Returns:

  • (String) —

    method + path



11
12
13
 
# File 'lib/jdoc/link.rb', line 11

def endpoint
  "#{method} #{path}"
end

#example_path ⇒ Object

Examples:

link.example_path #=> "GET /apps/1"

Raises:

  • (Rack::Spec::Mock::ExampleNotFound) 


69
70
71
72
73
74
75
76
77
78
79
 
# 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? ⇒ true, false

Returns True if this endpoint must have request body.

Returns:

  • (true, false) —

    True if this endpoint must have request body



147
148
149
 
# File 'lib/jdoc/link.rb', line 147

def has_request_body?
  ["PATCH", "POST", "PUT"].include?(method) && !request_parameters.empty?
end

#has_response_body? ⇒ true, false

We have a policy that we should not return response body to PUT and DELETE requests.

Returns:

  • (true, false) —

    True if this endpoint must have response body



153
154
155
 
# File 'lib/jdoc/link.rb', line 153

def has_response_body?
  @raw_link.media_type != "null"
end

#hyperlink ⇒ String

Returns Markdown styled link text for endpoint.

Examples:

link.hyperlink #=> "[GET /apps](#get-apps)"

Returns:

  • (String) —

    Markdown styled link text for endpoint



44
45
46
 
# File 'lib/jdoc/link.rb', line 44

def hyperlink
  "[#{endpoint}](#{anchor})"
end

#method ⇒ String

Returns Upper cased HTTP request method name.

Examples:

link.method #=> "GET"

Returns:

  • (String) —

    Upper cased HTTP request method name



51
52
53
 
# File 'lib/jdoc/link.rb', line 51

def method
  @method ||= @raw_link.method.to_s.upcase
end

#path ⇒ String

Note:

URI Template is replaced with placeholder

Returns Request path name, defined at href property.

Examples:

link.path #=> "GET /apps/:id"

Returns:

  • (String) —

    Request path name, defined at href property



59
60
61
62
63
 
# 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 ⇒ String?

Adds query string if a link has a schema property and method is GET

Examples:

link.query_string #=> "?type=Recipe"

Returns:

  • (String, nil) —

    A query string prefixed with ‘?` only to GET request



93
94
95
96
97
 
# File 'lib/jdoc/link.rb', line 93

def query_string
  if method == "GET" && !request_parameters.empty?
    "?#{request_parameters.to_query}"
  end
end

#request_body ⇒ String?

Returns Example request body in JSON format.

Returns:

  • (String, nil) —

    Example request body in JSON format



100
101
102
103
104
105
106
107
108
109
110
 
# 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 ⇒ Hash

Returns Example request parameters for this endpoint.

Returns:

  • (Hash) —

    Example request parameters for this endpoint



123
124
125
126
127
128
129
130
131
 
# 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 ⇒ Array<Jdoc::Property>

Returns Properties defined in this link’s schema property.

Returns:

  • (Array<Jdoc::Property>) —

    Properties defined in this link’s schema property.



134
135
136
137
138
139
140
141
142
143
144
 
# 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 ⇒ JsonSchema::Schema

Returns Request schema for this link.

Returns:

  • (JsonSchema::Schema) —

    Request schema for this link



193
194
195
 
# File 'lib/jdoc/link.rb', line 193

def request_schema
  @raw_link.schema
end

#resource ⇒ Json::Link::Resource

Note:

Resource means each property of top-level properties in this context

Returns:

  • (Json::Link::Resource) 


199
200
201
 
# File 'lib/jdoc/link.rb', line 199

def resource
  @resource ||= Resource.new(response_schema)
end

#response_body ⇒ String

Returns JSON response body generated from example properties.

Returns:

  • (String) —

    JSON response body generated from example properties



158
159
160
161
 
# 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 ⇒ String

Returns Preferred respone reason phrase for this endpoint.

Returns:

  • (String) —

    Preferred respone reason phrase for this endpoint



176
177
178
179
180
181
182
183
184
185
 
# 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 ⇒ JsonSchema::Schema

Returns Response schema for this link.

Returns:

  • (JsonSchema::Schema) —

    Response schema for this link



188
189
190
 
# File 'lib/jdoc/link.rb', line 188

def response_schema
  @raw_link.target_schema || @raw_link.parent
end

#response_status ⇒ Fixnum

Returns Preferred respone status code for this endpoint.

Returns:

  • (Fixnum) —

    Preferred respone status code for this endpoint



164
165
166
167
168
169
170
171
172
173
 
# 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 ⇒ String

For #<=> method

Returns:

  • (String) 


23
24
25
 
# File 'lib/jdoc/link.rb', line 23

def sort_key
  "#{path} #{method_order_score}"
end