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.
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
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
config.generate_on_demand = false
end
Copyright 2012 Oleg Khabarov, Jack Neto, The Working Group, Inc