Skip to content
Generate API documentation using integration tests in Rails 3
Ruby JavaScript
Find file

API Docs Build Status

A tool to help you generate documentation for your API using integration tests in Rails.


Add gem definition to your Gemfile and bundle install:

gem 'api_docs'

To access generated docs mount it to a path in your routes.rb like this:

mount ApiDocs::Engine => '/api-docs'

You may also want to add js/css to your asset pipeline manifests:

require api_docs

Documents view is made to work with Twitter Bootstrap css and js libraries.

Generating Api Docs

Documentation is automatically generated into yaml files from tests you create to test your api controllers. To start, let's create integration test by running rails g integration_test users. This will create a file for you to work with. Here's a simple test we can do:

class UsersTest < ActionDispatch::IntegrationTest
  def test_get_user
    user = users(:default)
    api_call(:get, '/users/:id', :id => user.to_param, :format => 'json') do |doc|
      assert_response :success
      assert_equal ({
        'id'    =>,
        'name'  =>
      }), JSON.parse(response.body)

  def test_get_user_failure
    api_call(:get, '/users/:id', :id => 'invalid', :format => 'json') do |doc|
      doc[:description] = 'When bad user id is passed'
      assert_response :not_found
      assert_equal ({
        'message' => 'User not found'
      }), JSON.parse(response.body)

Assuming that tests pass their details are doing to be recorded into docs/api/users.yml and they will look like this:

    method: GET
    path: /users/:id
      id: 12345
      format: json
    status: 200
      id: 12345
      name: John Doe
      description: When bad user id is passed
    method: GET
    path: /users/:id
      id: invalid
      format: json
    status: 404
      message: User not found


Just navigate to the path you mounted api_docs to. Perhaps http://yourapp/api-docs.


You can change the default configuration of this gem by adding the following code to your initializers folder:

ApiDocs.configure do |config|
  # folder path where api docs are saved to
  config.docs_path = Rails.root.join('doc/api')

  # controller that ApiDocs controller inherits from.
  # Useful for hiding it behind admin controller.
  config.base_controller = 'ApplicationController'

  # Remove doc files before running tests. False by default.
  config.reload_docs_folder = false

  # Generates docs on demand only. False by default.
  # When enabled docs will generate only if `ENV['API_DOCS']` is set
  attr_accessor :generate_on_demand


Api Docs Example

Copyright 2012 Oleg Khabarov, Jack Neto, The Working Group, Inc

Something went wrong with that request. Please try again.