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.

Escribe

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.

Escribe

What is the reason to use both rswag AND rspec-rails-swagger at the same time, is it related to your specific requirement regarding JSON API validation? Otherwise I believe that rswag can do anything rspec-rails-swagger does, I tried both and they're very very similar (almost to the extent that one seems a fork of the other), but rswag has more Github stars (if that means anything), seems slightly easier to use, and most importantly has a Swagger UI built in ... I think for the majority of use cases you wouldn't need to use both rswag and rspec-rails-swagger. – Mincey

rspec-rails-swagger DOES NOT INCLUDE Swagger UI to render the generated JSON doccs file. That was one of the reasons to use both. Another one - is that RSwag does not parse properly active_model_serializers responses and some tests just failed. – Escribe

Got it - rspec-rails-swagger does not include a UI, rswag does ... so what I meant was, why not just use rswag, but you've answered that one already, I asked a question which was already answered ... if ever we run into the same sort of problem then at least I know we could add rspec-rails-swagger to make it work again (maybe with some minor changes to the RSpec tests) – Mincey

@Escribe - have you managed to generate swagger docs when using the jsonapi-resources gem? Both that gem and rswag are what I need but I don't think they work well together. – Coligny

Nope, I don’t use jsonapi-resources gem. – Escribe

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

Lutero