Module: Grape::DSL::Desc

Extended by:
Settings
Included in:
API::Instance
Defined in:
lib/grape/dsl/desc.rb

Instance Attribute Summary

Attributes included from Settings

#inheritable_setting

Instance Method Summary collapse

Methods included from Settings

global_setting, namespace_setting, route_setting, top_level_setting

Instance Method Details

#desc(description, **options) { ... } ⇒ Object

Add a description to the next namespace or function.

Examples:


desc 'create a user'
post '/users' do
  # ...
end

desc 'find a user' do
  detail 'locates the user from the given user ID'
  failure [ [404, 'Couldn\'t find the given user' ] ]
  success User::Entity
end
get '/user/:id' do
  # ...
end

Parameters:

  • description (String) —

    descriptive string for this endpoint or namespace

  • options (Hash) —

    other properties you can set to describe the endpoint or namespace. Optional. Pass these as keyword arguments; passing a positional options Hash is deprecated.

Options Hash (**options):

  • :detail (String) —

    additional detail about this endpoint

  • :summary (String) —

    summary for this endpoint

  • :params (Hash) —

    param types and info. normally, you set these via the params dsl method.

  • :entity (Grape::Entity) —

    the entity returned upon a successful call to this action

  • :http_codes (Array[Array]) —

    possible HTTP codes this endpoint may return, with their meanings, in a 2d array

  • :default_response (Hash) —

    the definition and entity used to present this endpoint's default response. Was :default, which is deprecated.

  • :named (String) —

    a specific name to help find this route

  • :body_name (String) —

    override the autogenerated body name param

  • :headers (Hash) —

    HTTP headers this method can accept

  • :hidden (Boolean) —

    hide the endpoint or not

  • :deprecated (Boolean) —

    deprecate the endpoint or not

  • :is_array (Boolean) —

    response entity is array or not

  • :nickname (String) —

    nickname of the endpoint

  • :produces (Array[String]) —

    a list of MIME types the endpoint produce

  • :consumes (Array[String]) —

    a list of MIME types the endpoint consume

  • :security (Array[Hash]) —

    a list of security schemes

  • :tags (Array[String]) —

    a list of tags

Yields:

  • a block yielding an instance context with methods mapping to each of the above, except that :entity is also aliased as #success and :http_codes is aliased as #failure.



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/grape/dsl/desc.rb', line 56

def desc(description, **options, &config_block)
  resolved_options =
    if options.key?(:default)
      Grape.deprecator.warn('The `default` option of `desc` is deprecated. Use `default_response` instead.')
      # Rebuilt rather than mutated in place: an explicit +default_response+
      # still wins, since the merged Hash is the one that keeps its key.
      { default_response: options[:default] }.merge(options.except(:default))
    else
      options
    end

  settings =
    if config_block
      endpoint_config = defined?(configuration) ? configuration : nil
      Grape::Util::ApiDescription.new(description, endpoint_config, &config_block).settings
    else
      resolved_options.merge(description:)
    end
  # Only the route scope is consumed downstream (by +route+ and the
  # route's readers, e.g. +http_codes+); the namespace scope was
  # write-only, so it is no longer populated.
  inheritable_setting.route_description = settings
end