Skip to content
forked from GBH/api_docs

Generate API documentation using integration tests in Rails 3

License

Notifications You must be signed in to change notification settings

perfectline/api_docs

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

API Docs Build Status

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

Installation

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::Web => '/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'    => user.id,
        'name'  => user.name
      }), JSON.parse(response.body)
    end
  end

  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)
    end
  end
end

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

show:
  ID-f385895c2c5265b8a84d19b9885eebe0:
    method: GET
    path: /users/:id
    params:
      id: 12345
      format: json
    status: 200
    body:
      id: 12345
      name: John Doe
  ID-3691338c8b1f567ec48e0e2ebdba2e0d:
    meta:
      description: When bad user id is passed
    method: GET
    path: /users/:id
    params:
      id: invalid
      format: json
    status: 404
    body:
      message: User not found

Add Documentation on Controller

You just need to add a file on doc folder, with the same name yml file was generated. So in our case:

docs/api/users.yml docs/api/users.md

and after you will see something like this:

Api Docs Example

Usage

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

Configuration

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

  # Exclude params if they are always dynamic
  config.exclude_key_params = [:token]

end

Api Docs Example


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

About

Generate API documentation using integration tests in Rails 3

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Ruby 91.6%
  • CSS 6.1%
  • JavaScript 2.3%