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

  • :summary (String) —

    summary for this endpoint

  • :detail (String) —

    additional detail about 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

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

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



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

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.



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

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



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

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

#unset_description_field(field) ⇒ Object 



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

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