blog article draft

Automate API documentation with specs and CI/CD pipeline

 API documentation is very important to any application. This helps Mobile, Frontend developers and other API consumers for easy integration.

There are a couple of ways to maintain the documentation
Maintain separate repo to manage API documentation. So that they don’t commit every change of API docs into the codebase.
Use the same repo having docs or some other folder to manually update when there is a change in the APIs

It is very difficult to manually maintain the API documentation for every change. How can we automate this?

Rspec_api_documentation offers to generate documentation in various formats from the acceptance test. That’s awesome. But 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.
Here I will show you how to manage the doc in a clean way.

Now almost every project is using CI/CD pipelines. So we add a job to generate API docs and upload to s3. Inside the application just add a route and get the file from s3 and render

```
 gem 'rspec-rails'
 gem 'rspec_api_documentation'
```

I have choosen api_blueprint format which is my favourite foramt.

create a file spec/acceptance_helper.rb

```
require 'rails_helper'
require 'rspec_api_documentation'
require 'rspec_api_documentation/dsl'

RspecApiDocumentation.configure do |config|
  config.format = [:api_blueprint]
  config.request_headers_to_include = ['Content-Type', 'X-Access-Token']
  config.response_headers_to_include = ['Content-Type']
  config.api_name = 'Blog' # App name
end
```