API Doc Generation in Rails using RSpec and publish through CI/CD

surendrakonna — Mon, 06 Jul 2020 12:38:49 +0000

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.

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

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

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

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

Happy coding, stay updated, stay safe!

DEV Community: surendrakonna

API Doc Generation in Rails using RSpec and publish through CI/CD