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


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

def initialize(example)
   = example.
end

Instance Attribute Details

#metadataObject (readonly)

Returns the value of attribute metadata


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

def 
  
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)
  [][: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'
  }
}

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)
  [][:fields] ||= {}
  [][: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)
  [][:example_name] = value
end

#note(level = :info, value) ⇒ void

This method returns an undefined value.

For setting notes on an example


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}"
  [][:note] ||= {}
  [][: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

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)
  [][:parameters] ||= {}
  [][: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)
  [][:path] = value
end

#precedence(value) ⇒ Object

For setting the precedence of an example

Lower numbers will be ordered higher


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

def precedence(value)
  [][: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)
  [][: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)
  [][:resource_name] = value
end

#resource_precedence(value) ⇒ Object

For setting the precedence of the resource

Lower numbers will be ordered higher


44
45
46
# File 'lib/rspec_api_docs/dsl/doc_proxy.rb', line 44

def resource_precedence(value)
  [][: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

181
182
183
# File 'lib/rspec_api_docs/dsl/doc_proxy.rb', line 181

def response_body_after_hook(value)
  [][:response_body_after_hook] = value
end