UPGRADING.md

Upgrading Grape-swagger

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.

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

2. 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 ruby-grape/grape#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.