Swagger documentation tools for a Rails API application

Question

I googled a little bit to find a proper and easy to implement way to generate Swagger documentation for an existing Rails API app. To be short, there are 2 ways of implementation: either via controllers, models or via Rspec controller/request specs. The list is not too long and the choice is not so easy to make:

1. swagger-docs gem, - the oldest one. Pros: implementation is to be done in controllers. Cons: does not support Swagger V2 version and limited to 1.2 only.
2. swagger-blocks gem, - improved version of swagger-docs, supports Swagger V2 version, implementation is to be done in controllers, models. But I couldn't make it work, Swagger Editor could not parse the generated json file.
3. rswag gem: extends rspec-rails "request specs" with a Swagger-based DSL. Personally, I found it really difficult to implement in an existing Rails app for 2 reasons:
   • you will have to modify existing request specs
   • request specs look really weird and the syntax is not RSpec-ish.
4. rspec-rails-swagger gem: implementation via request specs. The same cons as above.

Does anybody know other gems to generate Swagger documentation for an existing Rails API app ? Any suggestions are welcome ! Thank you.

Answer 1

The solution I came to is as to use rswag gem and rspec-rails-swagger gem - install rswag gem by adding the following in your Gemfile:

#Gemfile
gem 'rswag-api'
gem 'rswag-ui'

group :development, :test do
  gem 'rspec-rails',         '~> 3.8.1'
  gem 'rspec-rails-swagger', '~> 0.1.5'
...
end

• run `bundle install``
• run rails g rswag:install to generate swagger_helper.rb
• to create a new request spec with rspec-rails-swagger, run rails generate rspec:swagger PostsController(adapt the name to your won controller you want to write the spec).
• write some specs as explained in rspec-rails-swagger README
• run bundle exec rake swagger to generate a swagger.json file.
• mount RSwag API and RSwag UI engines by adding the following lines to your routes.rb file:

#../config/routes.rb

Rails.application.routes.draw do
  mount Rswag::Ui::Engine => '/api-docs'
  mount Rswag::Api::Engine => '/api-docs'
...#other routes come here
end

• start up your rails server with rails s
• navigate to localhost:3000/api-docs to see the generated Swagger documentation.

Note: it works pretty good and replies to the client requirements, i.e.:

• generate Swagger 2.0 compatible documentation
• be able to execute requests directly from Swagger interface to see the real data

I removed rswag-specs gem from Gemfile because it could not validate response schema returned in JSON API format by active_model_serializers gem I use in my Rails API app. I had always to:

• generate the docs
• comment out failing tests
• then uncomment failing tests in case I need to generate some new documentation, that was really hard to maintain.

Now request specs are validated by RSpec and rspec-rails-swagger at the same time without hassle.

Hope this helps.