swagger for rails code example

Example: swagger ruby on rails

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.