OpenAPI documentation DSL improvements

[shirish-pampoorickal]

Please add any concerns, enhancements, bugs with the DSL for API documentation

[guanw88]

Enhancement Requests: 1) Allow the ability to customize text on a path parameter.

We can customize query params as follows, but there is no way to customize a path param.

valid :varname, :integer,
              required: true,
              info: "foo bar"

2) Allow the ability to add/customize different response codes.

We can add a response as below, but there is no way to specify the error code and the associated text.

response :hash do |response_fields|
              response_fields.field :title, :string, info: "title of the object"

              response_fields.fields :categories, :array, item_type: :hash do |category|
                category.field :name, :string, info: "the name of the assoccategory"
              end

              response_fields.fields :parent, :hash do |parent|
                parent.field :title, :string, info: "title of the parent"
              end
            end

[shirish-pampoorickal]

Enhancement: Only document presenters that are referenced in a documented controller

[kcotugno]

Currently search documentation cannot be customized. It would be great if we can!