Module: Grape::DSL::Desc

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

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.



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

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)
    ActiveSupport::Deprecation.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.



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/grape/dsl/desc.rb', line 82

def desc_container(endpoint_configuration)
  Module.new do
    include Grape::Util::StrictHashConfiguration.module(
      :summary,
      :description,
      :detail,
      :params,
      :entity,
      :http_codes,
      :named,
      :body_name,
      :headers,
      :hidden,
      :deprecated,
      :is_array,
      :nickname,
      :produces,
      :consumes,
      :security,
      :tags,
      :default
    )
    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