Adding Swagger Docs to a Rails 6 API Using Rswag

Swagger is a powerful set of tools for developing, testing, deploying, maintaining, and documenting APIs. The tools are found at swagger.io. When I first happened upon an API with Swagger documentation in place, I was amazed. The tools allowed navigating and testing the API in the browser with ease.

I recently began adding Swagger documentation to one of my projects, and I wanted to share the basics of that process.

This article assumes that a working Ruby on Rails API exists with models and controllers in place.

Add the Gems

Begin with the project Gemfile. The rswag gem contains what is needed to quickly integrate the API. That gem hooks into the rspec test tools, that gem is necessary for implementation.

gem “rswag”

To generate the integration files, the rspec-rails and rswag-specs gems should be added to the test and development groups.

group :development, :test do
  ...
  gem "rspec-rails"
  gem "rswag-specs"
end

bundle install to get the required libraries installed in the project.

Generate Integration Files

Next, run rails g rswag to generate the necessary helper files for testing spec and the documentation UI. Alternatively, those can be generated separately by runningrails g rswag:specs:install, rails g rswag:api:install, and rails g rswag:ui:install. The resulting helper file is found in /spec/swagger_helper.rb.

There should also be an addition to the routes.rb file allowing Rails to handle the requests properly.

mount Rswag::Ui::Engine => "/api-docs"
mount Rswag::Api::Engine => "/api-docs"

Also, run rails g rspec:install to generate the rails_helper.rb.

The documentation files will be generated from spec integration files. A starter file can be generated using a command similar torails generate rspec:swagger API::MyController.

Since my controller is routed to api/v1/encounters, the generator is rails generate rspec:swagger API::V1::Encounters_Controller.

That file must be modified to include specifications and sample data for the desired paths. Here’s an example of a post request for one of my routes.

require "swagger_helper"
RSpec.describe "api/v1/encounters_controller", type: :request do
  path "/api/v1/encounters" do
    post "Create an Encounter" do
      tags "Encounters"
      consumes "application/json"
      parameter name: :encounter, in: :body, schema: {
        type: :object,
        properties: {
          patient_id: { type: :integer },
          provider_id: { type: :integer },
        },
        required: ["patient_id", "provider_id"],
      }
response "201", "encounter created" do
        let(:encounter) { { patient_id: 10, provider_id: 1 } }
        run_test!
      end
response "422", "invalid request" do
        let(:encounter) { { patient_id: 10 } }
        run_test!
      end
    end
  end
end

Generate the Documentation

Now that the integration specifications are in place, run rails rswag:specs:swaggerize, or just rails rswag.

After starting the server and navigating to the /api-docs path, you’ll be treated to the wonder of Swagger documentation.

Screen Shot of Swagger API Documentation

The documentation depends on the spec integration files. As controller specs are added and made more robust, the developer makes gains in not only utilizing test-driven development but also remarkable API documentation.

I expect Swagger documentation and tools to become a regular part of my Ruby on Rails development, as it has for so many developers and organizations.

Happy Coding!