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
80
81
 
# File 'lib/grape/dsl/desc.rb', line 52

def desc(description, options = {}, &config_block)
  if block_given?
    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)
    unless options.empty?
      warn '[DEPRECATION] Passing a options hash and a block to `desc` is deprecated. Move all hash options to block.'
    end
    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.



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/grape/dsl/desc.rb', line 99

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
    )
    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

#description_field(field, value = nil) ⇒ Object 



83
84
85
86
87
88
89
90
91
 
# File 'lib/grape/dsl/desc.rb', line 83

def description_field(field, value = nil)
  description = route_setting(:description)
  if value
    description ||= route_setting(:description, {})
    description[field] = value
  elsif description
    description[field]
  end
end

#unset_description_field(field) ⇒ Object 



93
94
95
96
 
# File 'lib/grape/dsl/desc.rb', line 93

def unset_description_field(field)
  description = route_setting(:description)
  description.delete(field) if description
end