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
Happy coding, stay updated, stay safe!
Top comments (0)