In the recent years substantial percentage of my work as a backend developer was to create API for other components of larger systems. Mobile applications, rich javascript frontends and of course other backend services.
API is an interface between two software components. Very often those components are written by different people or even different teams.
At MONK, as Giuseppe described in his last post we test our API with Rspec. For the past several years, with every project we had to maintain three versions of API. Why three?

  • code – the logic of the application
  • tests – the QA assurance
  • documentation – the documents that are used by other teams to develop other pieces that will fit into the whole system

Ideally we would have a single point of reference – change once – update everything. To solve that problem we started using rspec_api_documentation and we are pretty happy with it. There are some alternatives.

How do we start?

To install just proceed with the usual update to your Gemfile:

gem 'rspec_api_documentation'

And bundle it:

$ bundle install

Prepare directory to separate acceptance tests:

$ mkdir spec/acceptance

Writing your first spec

$ vim spec/acceptance/authentication_spec.rb

ApiRspecDocumentation offers you a nice DSL to make your life easier.
Few highlights that are self explanatory

  • header
  • parameter (with arguments: required, scope)
  • explanation – little description added to the documentation

Example of the Authentication spec:


resource 'Authentication' do
  header 'X-Device-Id', :device_id
  let(:device_id) { 'some-device-id-12345' }
  post '/api/customers/sign_in' do
    parameter :email, 'Email', required: true, scope: user
    parameter :password, 'Password', required: true, scope: user
    let(:email)    { 'monkbot@wearemonk.com' }
    let(:password) { 'cracow' }
    example_request 'Logging in as customer' do
      explanation 'Some description'
      expect(status).to eq(200)
    end
  end
end

Generating documentation

Once you have written your specs you can proceed to generate documentation:

$ rake docs:generate 

Which will produce not so nicely looking documentation.
You can also add raddocs or apitome gems. Which will format the documentation using nicer CSS.
To use raddocs please add it to your Gemfile:

gem 'raddocs', group: [:development, :test, :staging]

and configure your config/routes.rb:

unless Rails.env.production?
  mount Raddocs::App => "/docs"
end

As you can see we expose documentation in development, test and staging that is used by our mobile developers. Our Jenkins server is generating API documentation on every build.
image
image


In our last project at MONK we wanted to save our time by not updating the code in three different places.
{}Good API Documentation

Don’t waste your time

We’ve made some research and found some gems that could solve some of the problems but only one that would solve all of them. RSpec Api Documentation.
I believe that any rails programmer knows what the RSpec is. 😉
The best of this gem is that you don’t have to create api documentation manually. During writing some acceptance test with all parameters and results, it will create documentation automatically (as a html, textile, json, markdown and others format).

How it works?

API Documentation use RSpec but also has own special parameters that should be explained but in general is quite easy.

resource 'Authentication' do
  header 'X-Device-Id', :device_id
  let(:device_id) { 'some-device-id-12345' }
  post '/api/customers/sign_in' do
    parameter :email, 'Email', required: true, scope: user
    parameter :password, 'Password', required: true, scope: user
    let(:email)    { 'monkbot@wearemonk.com' }
    let(:password) { 'cracovia' }
    example_request 'Logging in as customer' do
      explanation 'Some description'
      expect(status).to eq(200)
    end
  end
end

In the tests you can define some headers and name of this headers (for documentation): header 'X-Device-Id', :device_id. And then settting result by let(:device_id) { 'some-device-id-12345' }.
Also parameters are defining in the same way:
parameter :email, 'Email', required: true, scope: user. And to set this parameter you need add like before:let(:email) { 'monkbot@wearemonk.com' }.
In your documentation you can put some description putting explanation 'Some description'. On the end you can generate documentation by rake task: rake docs:generate.

Summary

If you want to have every time updated you API documentation you should use RSpec Api Documentation. It will don’t waste your time for paperwork. Writing Rspec tests parallely you write documentation.
It isn’t a great tool to kill two birds with one stone?

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>