Module: Grape::DSL::Desc

Includes:
Settings
Included in:
Configuration::ClassMethods
Defined in:
lib/grape/dsl/desc.rb

Constant Summary collapse

ROUTE_ATTRIBUTES = 
%i[
  body_name
  consumes
  default
  deprecated
  description
  detail
  entity
  headers
  hidden
  http_codes
  is_array
  named
  nickname
  params
  produces
  security
  summary
  tags
].freeze

Instance Attribute Summary

Attributes included from Settings

#inheritable_setting, #top_level_setting

Instance Method Summary collapse

Methods included from Settings

#api_class_setting, #get_or_set, #global_setting, #namespace_end, #namespace_inheritable, #namespace_inheritable_to_nil, #namespace_reverse_stackable, #namespace_reverse_stackable_with_hash, #namespace_setting, #namespace_stackable, #namespace_stackable_with_hash, #namespace_start, #route_end, #route_setting, #unset, #unset_api_class_setting, #unset_global_setting, #unset_namespace_inheritable, #unset_namespace_setting, #unset_namespace_stackable, #unset_route_setting, #within_namespace

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) (defaults to: {}) —

    other properties you can set to describe the endpoint or namespace. Optional.

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

  • :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.



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/grape/dsl/desc.rb', line 73

def desc(description, options = {}, &config_block)
  if config_block
    endpoint_configuration = if defined?(configuration)
                               # When the instance is mounted - the configuration is executed on mount time
                               if configuration.respond_to?(:evaluate)
                                 configuration.evaluate
                               # Within `given` or `mounted blocks` the configuration is already evaluated
                               elsif configuration.is_a?(Hash)
                                 configuration
                               end
                             end
    endpoint_configuration ||= {}
    config_class = desc_container(endpoint_configuration)

    config_class.configure do
      description description
    end

    config_class.configure(&config_block)
    Grape.deprecator.warn('Passing a options hash and a block to `desc` is deprecated. Move all hash options to block.') if options.any?
    options = config_class.settings
  else
    options = options.merge(description: description)
  end

  namespace_setting :description, options
  route_setting :description, options
end

#desc_container(endpoint_configuration) ⇒ Object

Returns an object which configures itself via an instance-context DSL.



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/grape/dsl/desc.rb', line 103

def desc_container(endpoint_configuration)
  Module.new do
    include Grape::Util::StrictHashConfiguration.module(*ROUTE_ATTRIBUTES)
    config_context.define_singleton_method(:configuration) do
      endpoint_configuration
    end

    def config_context.success(*args)
      entity(*args)
    end

    def config_context.failure(*args)
      http_codes(*args)
    end
  end
end