API Doc Generation in Rails using RSpec and CI/CD

Lifecycle of a product has to undergo so many steps to be categorized as a successful product and being a developer, we are always concerned about our product.

Testing is an essential part of every successful product. Tests play a vital role in any application. There are numerous advantages with test cases like upgrading an application to major versions, breaking monolithic into microservices, refactoring the codebase or finding bugs before deploying to QA. There are different types of tests mainly Unit tests, Functional tests Integration tests, Acceptance tests, Performance tests and end-to-end tests.

Credit: fiverr

Well, apart from it, maintaining API documentation is very important these days as it will be shared with Mobile, Frontend developers and other API consumers. Most people maintain the documentation manually within the application or use a new git repo to just maintain the documentation or using Postman collection. Awesome, but when there is a change in the API and doc requires your attention. You have to manually update API doc otherwise it is stale. Have you ever thought to automate this?

RSpec Api Documentation offers a feature to generate documentation in various formats from the acceptance tests. Isn’t that awesome. But you must be wondering that every time the content inside the API doc will change when you run specs. So committing the file every time with lots of changes is not a good idea and I tend to agree with you. Here I will show you how to manage the doc in a clean way.

The process is very simple yet too effective. Now almost every project uses CI/CD pipelines. So we simply add a job to generate API docs, upload it to s3, add a route to your application, get the file from s3 and render.

Let’s do it now

1. Add the following gems to your Gemfile under test group

gem 'rspec-rails'
gem 'rspec_api_documentation'

2. Run the bundler

3. Create a file under spec folder with filename acceptance_helper.rb and add the following snippet. Here I have choose api_blueprint format. You can choose any of your choice.

require 'rails_helper'
require 'rspec_api_documentation'
require 'rspec_api_documentation/dsl'
RspecApiDocumentation.configure do |config|
  config.format = [:api_blueprint] # use your own favourite format
  config.request_headers_to_include = ['Content-Type', 'X-Access-Token'] # replace X-Access-Token with your Authorization header.
  config.response_headers_to_include = ['Content-Type']
  config.api_name = 'Blog' # replace with your app name
end

4. Create spec/acceptance/users_spec.rb file

5. Generate docs

rake docs:generate

6. It’s time to configure Github actions. create workflows folder under .github of your project folder.

mkdir .github/workflows

7. Create .github/workflows/config.yml file. We need to configure AWS credentials( AWS_ACCESS_KEY_ID AWS_ACCESS_KEY_ID) in github actions. The best way to add environment variables is by using secrets. To add AWS credentials visit your GitHub project Settings->Secrets

8. Add route for API docs

Rails.application.routes.draw do
  namespace :api do
    resources :docs, only: [:index]
  end
end

It’s time to see the api documentation live

Github repository

Sample autogenerated doc

Happy coding, stay updated, stay safe!