Class: RspecApiDocs::Dsl::DocProxy

Inherits:
Object
  • Object
show all
Defined in:
lib/rspec_api_docs/dsl/doc_proxy.rb

Constant Summary collapse

UnknownNoteLevel = 
Class.new(BaseError)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(example) ⇒ DocProxy

Returns a new instance of DocProxy.



8
9
10
 
# File 'lib/rspec_api_docs/dsl/doc_proxy.rb', line 8

def initialize(example)
  @metadata = example.metadata
end

Instance Attribute Details

#metadata ⇒ Object (readonly)

Returns the value of attribute metadata.



6
7
8
 
# File 'lib/rspec_api_docs/dsl/doc_proxy.rb', line 6

def metadata
  @metadata
end

Instance Method Details

#description(value) ⇒ void

This method returns an undefined value.

For setting a description of the example.

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



53
54
55
 
# 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) ⇒ void

This method returns an undefined value.

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'
  }
}

Parameters:

  • name (Symbol) —

    the name of the response field

  • description (String) —

    a description of the response field

  • scope (Symbol, Array<Symbol>) (defaults to: []) —

    how the field is scoped

  • type (String) (defaults to: nil)
  • example (defaults to: nil) —

    an example value



90
91
92
93
94
95
96
97
98
 
# 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) ⇒ void

This method returns an undefined value.

For setting the name of the example.

E.g. “Returns a Character”



17
18
19
 
# 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) ⇒ void

This method returns an undefined value.

For setting notes on an example

Parameters:

  • level (Symbol) (defaults to: :info) —

    the level of the note

  • value (String) —

    the note, :success, :info, :warning, or :danger



134
135
136
137
138
139
 
# 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) ⇒ void

This method returns an undefined value.

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

Parameters:

  • name (Symbol) —

    the name of the parameter

  • description (String) —

    a description of the parameter

  • scope (Symbol, Array<Symbol>) (defaults to: []) —

    how the parameter is scoped

  • type (String) (defaults to: nil)
  • required (true, false) (defaults to: false) —

    if the field is required



119
120
121
122
123
124
125
126
127
 
# 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) ⇒ void

This method returns an undefined value.

For setting the request path of the example.

E.g. “/characters/:id”



62
63
64
 
# File 'lib/rspec_api_docs/dsl/doc_proxy.rb', line 62

def path(value)
  metadata[METADATA_NAMESPACE][:path] = value
end

#precedence(value) ⇒ Object

For setting the precedence of an example

Lower numbers will be ordered higher

Parameters:

  • value (Integer) —

    the precedence



146
147
148
 
# File 'lib/rspec_api_docs/dsl/doc_proxy.rb', line 146

def precedence(value)
  metadata[METADATA_NAMESPACE][:example_precedence] = value
end

#resource_description(value) ⇒ void

This method returns an undefined value.

For setting the description of the resource.

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



35
36
37
 
# 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) ⇒ void

This method returns an undefined value.

For setting the name of the resource.

E.g. “Characters”



26
27
28
 
# 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) ⇒ Object

For setting the precedence of the resource

Lower numbers will be ordered higher

Parameters:

  • value (Integer) —

    the precedence



44
45
46
 
# 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) ⇒ void

This method returns an undefined value.

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

Parameters:

  • value (Lambda) —

    after hook lambda



181
182
183
 
# 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