Route#options and Route#settings are confusing

[ericproulx]

Following the documentation, we can use Route#options and Route#settings.

Note that difference of Route#options and Route#settings.

The options can be referred from your route, it should be set by specifing key and value on verb methods such as get, post and put. The settings can also be referred from your route, but it should be set by specifing key and value on route_setting.

Somehow, its all mixed up and data can be accessed through options, attributes and settings

class MyApi < Grape::API
  namespace 'ns' do
    desc 'ns second', foo: 'bar', params: { a_desc_param: { desc: 'A described param', type: 'string' } }
    route_setting :a_route_setting, :a_route_setting_value
    params do
      optional :a_param, type: Integer
    end
    get(a_verb_setting: :a_verb_setting_value) { }
  end
end

MyApi::routes[0].options
# {
#   :params=>{
#     "a_param"=>{:required=>false, :type=>"Integer"},
#     :a_desc_param=>{:desc=>"A described param", :type=>"string"}
#   },
#   :foo=>"bar",
#   :description=>"ns second",
#   :a_verb_setting=>:a_verb_setting_value,
#   :namespace=>"/ns",
#   :version=>nil,
#   :requirements=>{},
#   :prefix=>nil,
#   :anchor=>true,
#   :settings=>{
#     :description=>{
#       :foo=>"bar",
#       :params=>{
#         :a_desc_param=>{:desc=>"A described param", :type=>"string"}
#       }, :description=>"ns second"
#     },
#     :a_route_setting=>:a_route_setting_value
#   },
#   :forward_match=>nil,
#   :suffix=>"(.:format)",
#   :method=>"GET"
# }
MyApi::routes[0].attributes.to_h
# {
#   :params=>{
#     "a_param"=>{:required=>false, :type=>"Integer"},
#     :a_desc_param=>{:desc=>"A described param", :type=>"string"}
#   },
#   :foo=>"bar",
#   :description=>"ns second",
#   :a_verb_setting=>:a_verb_setting_value,
#   :namespace=>"/ns",
#   :version=>nil,
#   :requirements=>{},
#   :prefix=>nil,
#   :anchor=>true,
#   :settings=>{
#     :description=>{
#       :foo=>"bar",
#       :params=>{:a_desc_param=>{:desc=>"A described param", :type=>"string"}},
#       :description=>"ns second"
#     },
#     :a_route_setting=>:a_route_setting_value
#   },
#   :forward_match=>nil,
#   :suffix=>"(.:format)",
#   :request_method=>"GET"
# }
MyApi::routes[0].settings
# {
#   :description=>{
#     :foo=>"bar",
#     :params=>{
#       :a_desc_param=>{:desc=>"A described param", :type=>"string"}
#     },
#     :description=>"ns second"
#   },
#   :a_route_setting=>:a_route_setting_value
# }

• params can be defined through the desc DSL and it is merged with the params DSL which is confusing
• desc attributes can be accessed through options[], settings[] and like a getter e.g MyApi::routes[0].description == MyApi::routes[0].options[:description]`

Should options contains just the verb options (if any) and settings just the route options ?
Should we keep internal values somewhere else ? For instance, a user could override requirements through the desc DSL.

Thanks

[dblock]

Eh, this is indeed confusing. I like both suggestions, would start with internal values, moving those should probably not break specs.