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.



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/grape/dsl/desc.rb', line 50

def desc(description, options = {}, &config_block)
  if block_given?
    config_class = desc_container

    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 ⇒ Object

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



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

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

    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 



71
72
73
74
75
76
77
78
79
 
# File 'lib/grape/dsl/desc.rb', line 71

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 



81
82
83
84
 
# File 'lib/grape/dsl/desc.rb', line 81

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