UPGRADING.md

June 26, 2026 ยท View on GitHub

Upgrading Grape-swagger

Upgrading to >= 2.2.0

  • Minimum Grape version is now >= 2.1 (was >= 1.7). Grape 1.8.0 and 2.0.0 cannot be used on Ruby 3.3+ because of an upstream Mustermann/forwardable incompatibility; the CI rows for those combinations were already failing on master and have been removed.

  • SwaggerRouting and SwaggerDocumentationAdder are now also namespaced under GrapeSwagger::. The top-level constants remain as deprecated compatibility aliases for now and are planned for removal in grape-swagger 3.0; prefer GrapeSwagger::SwaggerRouting and GrapeSwagger::SwaggerDocumentationAdder in downstream code.

  • type: 'Object' (and other string type names) in params blocks: Grape 3.2+ rejects string type names. If you previously declared a swagger-only documentation hint via params { optional :foo, type: 'Object' }, move the type under documentation::

    optional :foo, documentation: { type: 'Object' }

    grape-swagger picks the type up from the merged settings unchanged, so the swagger output is identical.

  • Custom type classes used via type: MyClass must implement MyClass.parse(value) (arity 1) on Grape 3.2+; otherwise Grape's dry-types lookup raises ArgumentError. Grape::Entity already provides parse; Representable::Decorator and plain Ruby classes need to define it explicitly:

    class MyType
  def self.parse(value) = new(value)
  # ...
end

  • Multi-type params (type: [A, B]) on Grape 3.2+: swagger output now reflects the first declared type (e.g. type: [Integer, Float] produces "integer"). Previously, Grape 3.2+ serialized the VariantCollectionCoercer wrapper via #to_s, leaking "#<Grape::Validations::Types::VariantCollectionCoercer:0x...>" into the documentation. No action required, but if you were programmatically post-processing that string, the fix will change the output.

Upgrading to >= x.y.z

  • Grape-swagger now documents array parameters within an object schema in Swagger. This aligns with grape's JSON structure requirements and ensures the documentation is correct.

    • Previously, arrays were documented as standalone arrays, which could be incorrect based on grape's expectations.
    • Check your API documentation and update your code or tests that use the old array format.

    Attention: This update may require you to make changes to ensure your API integrations continue to work correctly. For detailed reasons behind this update, refer to GitHub issue #666.

Upgrading to >= 1.5.0

  • The names generated for body parameter definitions and their references has changed. It'll now include the HTTP action as well as any path parameters.
    • E.g, given a PUT /things/:id endpoint, paths.things/{id}.put.parameters in the generated Swaggerfile will contain the following:
    • With grape-swagger < 1.5.0: { "name": "Things", ..., "schema": { "$ref": "#/definitions/putThings" } }
    • With grape-swagger >= 1.5.0: { "name": "putThingsId", ..., "schema": { "$ref": "#/definitions/putThingsId" } }
  • If you use the nickname option for an endpoint, that nickname will be used for both the parameter name and its definition reference.
    • E.g., if the endpoint above were nicknamed put-thing, the generated Swaggerfile will contain { "name": "put-thing", ..., "schema": { "$ref": "#/definitions/put-thing" } }

Upgrading to >= 1.4.2

  • additionalProperties has been deprecated and will be removed in a future version of grape-swagger. It has been replaced with additional_properties.
  • The value of the enum attribute is now always an Array. If it has only one value, it will be a one-element Array.

Upgrading to >= 1.4.0

  • Official support for ruby < 2.5 removed, ruby 2.5 only in testing mode, but no support.

Upgrading to >= 1.3.0

  • The model (entity) description no longer comes from the route description. It will have a default value: <<EntityName>> model.

Upgrading to >= 1.2.0

  • The entity_name class method is now called on parent classes for inherited entities. Now you can do this
module Some::Long::Module
  class Base < Grape::Entity
    # ... other shared logic
    def self.entity_name
      "V2::#{self.to_s.demodulize}"
    end
  end

  def MyEntity < Base
    # ....
  end

  def OtherEntity < Base
    # revert back to the default behavior by hiding the method
    private_class_method :entity_name
  end
end
  • Full class name is modified to use _ separator (e.g. A_B_C instead of A::B::C).

Upgrading to >= 1.1.0

Full class name is used for referencing entity by default (e.g. A::B::C instead of just C). Entity and Entities suffixes and prefixes are omitted (e.g. if entity name is Entities::SomeScope::MyFavourite::Entity only SomeScope::MyFavourite will be used).

Upgrading to >= 0.26.1

The format can now be specified, to achieve it for definition properties one have to use grape-swagger-entity >= 0.1.6.

Usage of option markdown won't no longer be supported, cause OAPI accepts GFM and plain text. (see: description of Info)

Upgrading to >= 0.25.2

Avoids ambiguous documentation of array parameters, by enforcing correct usage of both possibilities:

  1. Array of primitive types
params do
  requires :foo, type: Array[String]
end
  1. Array of objects
params do
  requires :put_params, type: Array do
    requires :op, type: String
    requires :path, type: String
    requires :value, type: String
  end
end

Upgrading to >= 0.25.0

The global tag set now only includes tags for documented routes. This behaviour has impact in particular for calling the documtation of a specific route.

Upgrading to >= 0.21.0

With grape >= 0.21.0, grape-entity support moved to separate gem grape-swagger-entity, if you use grape entity, update your Gemfile:

gem 'grape-swagger'
gem 'grape-swagger-entity'

add_swagger_documentation has changed from

  add_swagger_documentation \
    api_version: '0.0.1'

to

  add_swagger_documentation \
    doc_version: '0.0.1'

The API version self, would be set by grape, see -> spec for #403.

Upgrading to >= 0.10.2

With grape >= 0.12.0, support for notes is replaced by passing a block detail option specified. For future compatibility, update your code:

desc 'Get all kittens!', notes: 'this will expose all the kittens'

to

 desc 'Get all kittens!' do
  detail 'this will expose all the kittens'
end

Be aware of https://github.com/ruby-grape/grape/issues/920, currently grape accepts either an option hash OR a block for desc.

Upgrading to >= 0.9.0

Grape-Swagger-Rails

If you're using grape-swagger-rails, remove the .json extension from GrapeSwaggerRails.options.url.

For example, change

GrapeSwaggerRails.options.url = '/api/v1/swagger_doc.json'

to

GrapeSwaggerRails.options.url = '/api/v1/swagger_doc'

See #187 for more information.

Grape 0.10.0

If your API uses Grape 0.10.0 or newer with a single format :json directive, add hide_format: true to add_swagger_documentation. Otherwise nested routes will render with .json links to your API documentation, which will fail with a 404 Not Found.

Upgrading to >= 0.8.0

Changes in Configuration

The following options have been added, removed or have been changed in the grape-swagger interface:

  • markdown: true/false => markdown: GrapeSwagger::Markdown::KramdownAdapter

Markdown

You can now configure a markdown adapter. This was originally changed because of performance issues with Kramdown and the markdown option no longer takes a boolean argument. Built-in adapters include Kramdown and Redcarpet.

Kramdown

To configure the markdown with Kramdown, add the kramdown gem to your Gemfile:

gem 'kramdown'

Configure grape-swagger as follows:

add_swagger_documentation (
    markdown: GrapeSwagger::Markdown::KramdownAdapter
)

Redcarpet

To configure markdown with Redcarpet, add the redcarpet and the rouge gem to your Gemfile. Note that Redcarpet does not work with JRuby.

gem 'redcarpet'
gem 'rouge'

Configure grape-swagger as follows:

add_swagger_documentation (
    markdown: GrapeSwagger::Markdown::RedcarpetAdapter
)

See #142 and documentation section Markdown in Notes for more information.