class RspecApiDocs::Dsl::DocProxy

Constants

UnknownNoteLevel

Attributes

metadata[R]

Public Class Methods

new(example) click to toggle source
# File lib/rspec_api_docs/dsl/doc_proxy.rb, line 8
def initialize(example)
  @metadata = example.metadata
end

Public Instance Methods

description(value) click to toggle source

For setting a description of the example.

E.g. “Allows you to return a single character.”

@return [void]

# File lib/rspec_api_docs/dsl/doc_proxy.rb, line 53
def description(value)
  metadata[METADATA_NAMESPACE][:description] = value
end
field(name, description, scope: [], type: nil, example: nil) click to toggle source

For setting response fields of a request.

Usage:

doc do
  field :id, 'The id of a character', scope: :character
  field :name, "The character's name", scope: :character
end

For a response body of:

{
  character: {
    id: 1,
    name: 'Finn The Human'
  }
}

@param name [Symbol] the name of the response field @param description [String] a description of the response field @param scope [Symbol, Array<Symbol>] how the field is scoped @param type [String] @param example an example value @return [void]

# File lib/rspec_api_docs/dsl/doc_proxy.rb, line 90
def field(name, description, scope: [], type: nil, example: nil)
  metadata[METADATA_NAMESPACE][:fields] ||= {}
  metadata[METADATA_NAMESPACE][:fields][{name: name, scope: scope}] = {
    description: description,
    scope: Array(scope),
    type: type,
    example: example,
  }
end
name(value) click to toggle source

For setting the name of the example.

E.g. “Returns a Character”

@return [void]

# File lib/rspec_api_docs/dsl/doc_proxy.rb, line 17
def name(value)
  metadata[METADATA_NAMESPACE][:example_name] = value
end
note(level = :info, value) click to toggle source

For setting notes on an example

@param level [Symbol] the level of the note @param value [String] the note, :success, :info, :warning, or :danger @return [void]

# File lib/rspec_api_docs/dsl/doc_proxy.rb, line 134
def note(level = :info, value)
  %i[success info warning danger].include?(level) or
    raise UnknownNoteLevel, "unknown note level #{level.inspect}"
  metadata[METADATA_NAMESPACE][:note] ||= {}
  metadata[METADATA_NAMESPACE][:note][level] = value
end
param(name, description, scope: [], type: nil, required: false) click to toggle source

For setting params of a request.

Usage:

doc do
  param :id, 'The id of a character', required: true
  param :name, 'A tag on a character', scope: :tag
end

For a path of:

/characters/:id?tag[name]=:name

@param name [Symbol] the name of the parameter @param description [String] a description of the parameter @param scope [Symbol, Array<Symbol>] how the parameter is scoped @param type [String] @param required [true, false] if the field is required @return [void]

# File lib/rspec_api_docs/dsl/doc_proxy.rb, line 119
def param(name, description, scope: [], type: nil, required: false)
  metadata[METADATA_NAMESPACE][:parameters] ||= {}
  metadata[METADATA_NAMESPACE][:parameters][{name: name, scope: scope}] = {
    description: description,
    scope: Array(scope),
    type: type,
    required: required,
  }
end
path(value) click to toggle source

For setting the request path of the example.

E.g. “/characters/:id”

@return [void]

# File lib/rspec_api_docs/dsl/doc_proxy.rb, line 62
def path(value)
  metadata[METADATA_NAMESPACE][:path] = value
end
precedence(value) click to toggle source

For setting the precedence of an example

Lower numbers will be ordered higher

@param value [Integer] the precedence

# File lib/rspec_api_docs/dsl/doc_proxy.rb, line 146
def precedence(value)
  metadata[METADATA_NAMESPACE][:example_precedence] = value
end
resource_description(value) click to toggle source

For setting the description of the resource.

E.g. “Orders can be created, viewed, and deleted”

@return [void]

# File lib/rspec_api_docs/dsl/doc_proxy.rb, line 35
def resource_description(value)
  metadata[METADATA_NAMESPACE][:resource_description] = value
end
resource_name(value) click to toggle source

For setting the name of the resource.

E.g. “Characters”

@return [void]

# File lib/rspec_api_docs/dsl/doc_proxy.rb, line 26
def resource_name(value)
  metadata[METADATA_NAMESPACE][:resource_name] = value
end
resource_precedence(value) click to toggle source

For setting the precedence of the resource

Lower numbers will be ordered higher

@param value [Integer] the precedence

# File lib/rspec_api_docs/dsl/doc_proxy.rb, line 44
def resource_precedence(value)
  metadata[METADATA_NAMESPACE][:resource_precedence] = value
end
response_body_after_hook(value) click to toggle source

For passing a lambda to modify the response body

This is useful if the entire body of the response isn't relevant to the documentation example.

With a response body of:

{
  characters: [
    {
      id: 1,
      name: 'Finn The Human',
    },
    {
      id: 2,
      name: 'Jake The Dog',
    },
  ],
}

Usage:

doc do
  response_body_after_hook -> (parsed_response_body) {
    parsed_response_body[:characters].delete_if { |character| character[:id] != 1 }
    parsed_response_body
  }
end

@param value [Lambda] after hook lambda @return [void]

# File lib/rspec_api_docs/dsl/doc_proxy.rb, line 181
def response_body_after_hook(value)
  metadata[METADATA_NAMESPACE][:response_body_after_hook] = value
end