Route#options and Route#settings are confusing

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

Start by reproducing the documented example and inspecting the Route#options, Route#settings, and Route#attributes entry points, along with the desc, params, and route_setting DSL behavior. Trace how verb options, route settings, description attributes, and internal values are merged, then define and validate a consistent separation of those public interfaces.