RSpec Rails Swagger
This gem helps you generate Swagger docs by using RSpec to document the paths.
You execute a command to run the tests and generate the .json
output. Running
the tests ensures that your API and docs are in agreement, and generates output
that can be used as examples.
The design of this was heavily influenced by the awesome swagger_rails gem.
Setup
Add the gem to your Rails app's Gemfile
:
group :development, :test do
gem 'rspec-rails-swagger'
end
Update your bundle:
bundle install
If you don't have a spec/rails_helper.rb
file:
rails generate rspec:install
Create the spec/swagger_helper.rb
file:
rails generate rspec:swagger_install
Documenting Your API
Now you can edit spec/swagger_helper.rb
and start filling in the top level
Swagger documention, e.g. basePath, definitions,
parameters,
tags, etc.
You can use the generator to create a spec to documentation a controller:
rails generate rspec:swagger PostsController
That will create a spec/requests/posts_spec.rb
file with the paths, operations
and some default requests filled in. With the structure in place you should only
need to add before
calls to create records and then update the let
s to
return the appropriate values.
Generate the JSON
To create the Swagger JSON files use the rake task:
bundle exec rake swagger
Now you can use Swagger UI or the renderer of your choice to display the formatted documentation. swagger_engine works pretty well and supports multiple documents.