A D Vishnu Prasad

Director of Cloud Engineering @ Team8Solutions, Freelancer

Generate API Documentation Using Rspec Acceptance Tests

Step 1:

Install required gems

1
2

gem 'rspec_api_documentation'
gem 'raddocs'

Step 2:

Create acceptance_helper.rb in spec folder

acceptance_helper.rb
1
2
3
4
5
6
7
8
9
10
11
12
13

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

RspecApiDocumentation.configure do |config|
  config.format = :json
  config.curl_host = 'http://fysquare.dev' # Will be used in curl request
  config.api_name = "FySquare API" # Your API name
  config.request_headers_to_include = ["Host", "Content-Type"]
  config.response_headers_to_include = ["Host", "Content-Type"]
  config.curl_headers_to_filter = ["Authorization"] # Remove this if you want to show Auth headers in request
  config.keep_source_order = true
end

Create raddoc.rb in initializers

raddoc.rb
1
2
3

Raddocs.configure do |config|
  config.api_name = "FySquare API Documentation"
end

Add API route in config.rb

routes.rb
1
2

mount Raddocs::App => "/api_docs"
end

Step 3:

Now you need to write acceptance specs which will be used to generate docs.

Below is the spec for listing users API. You can change the params depends on your API.

users_spec.rb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

require 'acceptance_helper'

resource "User", acceptance: true do
  let(:user) { FactoryGirl.create(:user) }
  before do
    header 'Authorization', 'Auth code'
    header 'Content-Type', 'application/json'
  end

  get "/api/users" do
    example_request "Listing Users" do
      explanation "List all the users in the system"
      expect(status).to eq 200
    end

    parameter :ids, "List of user ids to be fetched"
    parameter :email, "Search users by email"
    parameter :page, "Page to view"
    example "Get users by params" do
      explanation "Get users by params"

      do_request(:ids => [user.id])
      expect(status).to eq 200

      do_request(:email => ['foo@example.com', 'doo@example.com'])
      expect(status).to eq 200

    end
  end

  get "/api/users/:id" do
    let(:id) { user.id }
    example_request "Getting a specific user" do
      expect(status).to eq(200)
    end
  end
end

Step 4:

Run this rake command to generate API.

1

rake docs:generate

Now navigate to localhost:3000/docs

API docs image