Swagger documentation tools for a Rails API application - swagger-ui

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:
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.
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.
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.
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.

Answer 2

Our working solution is to use:
swagger-blocks gem to generate the Swagger JSON
Swagger UI Console Chrome
Extension to provide the Swagger UI