API Doc Generation in Rails using RSpec and CI/CD

The 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.

Additionally, maintaining API documentation is very important these days as it is 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. But when there is a change in the API, 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. Every time the content inside the API doc will change when you run the specs. So committing the file every time with lots of changes is not a good idea. Here are some steps 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 the spec folder with filename acceptance_helper.rb and add the following snippet. Here the chosen format is api_blueprint. You can choose any, as per 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. (link)

require 'acceptance_helper'
resource 'Users' do
  header "Content-Type", "application/json"
  route "/api/users", "Add User" do
    parameter :name, "User name", type: :string, example: 'John Wick', required: true
    parameter :email, "User email", type: :string, example: 'user@test.com', required: true
    parameter :password, "User password", type: :string, required: true
    parameter :password_confirmation, type: :string, required: true
    post 'Create User' do
      let(:raw_post) { params.to_json }
      context 'when success' do
        let(:params) { { user: { name: 'Surendra', email: 'user@test.com', password: 'Apple123', password_confirmation: 'Apple123'} } }
        example '200' do
          # Act
          do_request
          # Assert
          expect(status).to eq(200)
        end
      end
      context 'when failed' do
        let(:params) { { user: { name: 'Surendra', email: ''} } }
        example '422' do
          # Act
          do_request
          # Assert
          expect(status).to eq(422)
        end
      end
    end
  end
  route "/api/users/:id", "Get User" do
    header 'X-ACCESS-TOKEN', :access_token
    parameter :id, "User ID", type: :integer, example: '123', required: true
    get 'Get User' do
      context 'when success' do
        let(:id) { FactoryBot.create(:user).id}
        # let(:params) { { user: { name: 'Surendra', email: 'user@test.com', password: 'Apple123', password_confirmation: 'Apple123'} } }
        example '200' do
          # Act
          do_request
          # Assert
          expect(status).to eq(200)
        end
      end
    end
  end
end

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 (link)

name: API Documentation
on:
  push:
    branches:
      - master
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      db:
        image: postgres:11
        ports: ['5432:5432']
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v2
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-west-2
      - name: Setup Ruby
        uses: actions/setup-ruby@v1
        with:
          ruby-version: 2.7.1
      - uses: actions/setup-node@v1
        with:
          node-version: '11.x'
      - name: Install PostgreSQL 11 client
        run: |
          sudo apt-get -yqq install libpq-dev
      - name: Build and run tests
        env:
          RAILS_ENV: test
          DB_HOST: localhost
          DB_USER: postgres
          DB_PASS: postgres
        run: |
          gem install bundler:1.17.2
          bundle install --jobs 4 --retry 3
          bundle exec rake db:drop db:create db:schema:load
          bundle exec rspec
          npm install -g aglio
          bundle exec rake docs:generate
          aglio -i doc/api/index.apib --theme-template triple -o api_doc.html
          aws s3 sync . s3://blog-api-docs --exclude "*" --include "api_doc.html"

8. Add route for API docs (link)

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

class Api::DocsController < ApplicationController
  def index
    @html = Aws::S3::Object.new(ENV['API_DOCS_BUCKET'], ENV['API_DOCS_FILE_NAME']).get.body.string
    render html: @html.html_safe, content_type: "text/html"
  end
end

It’s time to see the API documentation live

Github repository

Sample autogenerated doc

Happy coding, stay updated, stay safe!