Automate your documentation writing process! Dox generates API documentation from Rspec controller/request specs in a Rails application. It formats the tests output in the OpenApi format. Use the ReDoc renderer for generating and displaying the documentation as HTML.
Here's a demo app.
Add this line to your application's Gemfile:
group :test do
gem 'dox', require: false
end
And then execute:
$ bundle
Or install it yourself as:
$ gem install dox
Require Dox in the rails_helper:
require 'dox'
Set these optional options in the rails_helper:
Option | Value | Description |
---|---|---|
descriptions_location | Pathname instance or fullpath string (can be an array) | Folder containing markdown descriptions of resources. |
schema_request_folder_path | Pathname instance or fullpath string | Folder with request schemas of resources. |
schema_response_folder_path | Pathname instance or fullpath string | Folder with response schemas of resources. |
schema_response_fail_file_path | Pathname instance or fullpath string | Json file that contains the default schema of a failed response. |
openapi_version | string | Openapi version (default: '3.0.0' ) |
api_version | string | Api Version (default: '1.0') |
title | string | Documentation title (default: 'API Documentation') |
header_description | Pathname instance or string | Description (header) of the documentation (default: ''). If pathname ends with .md , the file is looked in descriptions_location folder |
headers_whitelist | Array of headers (strings) | Requests and responses will by default list only Content-Type header. To list other http headers, you must whitelist them. |
check_file_presence_on_init | boolean | Option defaults to true. In case an .md file doesn't exist, dox won't wait for the specs to pass before attempting to print the documentation. It will raise an error early during resource initialization. If you're calling Dox.configure multiple times during the spec suite, you might want to set this to false. |
Example:
Dox.configure do |config|
config.descriptions_location = Rails.root.join('spec/docs/v1/descriptions')
config.schema_request_folder_path = Rails.root.join('spec/docs/v1/schemas')
config.schema_response_folder_path = Rails.root.join('spec/support/v1/schemas')
config.schema_response_fail_file_path = Rails.root.join('spec/support/v1/schemas/error.json')
config.headers_whitelist = ['Accept', 'X-Auth-Token']
config.title = 'API'
config.api_version = '2.0'
config.header_description = 'api_description.md'
end
Define a descriptor module for a resource using Dox DSL:
module Docs
module V1
module Bids
extend Dox::DSL::Syntax
# define common resource data for each action
document :api do
resource 'Bids' do
group 'Bids'
desc 'bids.md'
end
end
# define data for specific action
document :index do
action 'Get bids'
end
end
end
end
You can define the descriptors for example in specs/docs folder, just make sure you load them in the rails_helper.rb:
Dir[Rails.root.join('spec/docs/**/*.rb')].each { |f| require f }
Include the descriptor modules in a controller and tag the specs you want to document with dox:
describe Api::V1::BidsController, type: :controller do
# include resource module
include Docs::V1::Bids::Api
describe 'GET #index' do
# include action module
include Docs::V1::Bids::Index
it 'returns a list of bids', :dox do
get :index
expect(response).to have_http_status(:ok)
end
end
end
And generate the documentation.
Before running into any more details, here's roughly how the generated OpenApi document is structured:
- openapi
- info
- paths
- action 1
- tag1
- example 1
- example 2
- action 2
- tag2
- example 3
- action 1
- x-tagGroups - tags1 - tag 1 - tag 2 - tags2 - tag 3 - tag 4
- tags
- tag1
- tag2
OpenApi and info are defined in a json file as mentioned before. Examples are concrete test examples (you can have multiple examples for both happy and fail paths). They are completely automatically generated from the request/response objects. And you can customize the following in the descriptors:
- x-tagGroup (resourceGroup)
- tag (resource)
- action
- example
ResourceGroup contains related resources and is defined with:
- name (required)
- desc (optional, inline string or relative filepath)
Example:
document :bids_group do
group 'Bids' do
desc 'Here are all bid related resources'
end
end
You can omit defining the resource group, if you don't have any description for it. Related resources will be linked in a group by the group option at the resource definition.
Resource contains actions and is defined with:
- name (required)
- group (required; to associate it with the related group)
- desc (optional; inline string or relative filepath)
Example:
document :bids do
resource 'Bids' do
group 'Bids'
desc 'bids/bids.md'
end
end
Usually you'll want to define resourceGroup and resource together, so you don't have to include 2 modules with common data per spec file:
document :bids_common do
group 'Bids' do
desc 'Here are all bid related resources'
end
resource 'Bids' do
group 'Bids'
desc 'bids/bids.md'
end
end
Action contains examples and is defined with:
- name (required)
- path* (optional)
- verb* (optional)
- params (optional; depricated)
- query_params (optional; more info)
- desc (optional; inline string or relative filepath)
- request_schema (optional; inline string or relative filepath)
- response_schema_success (optional; inline string or relative filepath)
- response_schema_fail (optional; inline string or relative filepath)
* these optional attributes are guessed (if not defined) from the request object of the test example and you can override them.
Example:
show_params = { id: { type: :number, required: :required, value: 1, description: 'bid id' } }
query_params = [ {
"in": "query",
"name": "filter",
"required": false,
"style": "deepObject",
"explode": true,
"schema": {
"type": "object",
"required": ["updated_at_gt"],
"example": {
"updated_at_gt": "2018-02-03 10:30:00"
},
"properties": {
"updated_at_gt": {
"type": "string",
"title": "date"
}
}
}
]
document :action do
action 'Get bid' do
path '/bids/{id}'
verb 'GET'
params show_params
query_params query_params
desc 'Some description for get bid action'
request_schema 'namespace/bids'
response_schema_success 'namespace/bids_s'
response_schema_fail 'namespace/bids_f'
end
end
Documentation is generated in 2 steps:
-
generate OpenApi json file:
bundle exec rspec --tag apidoc -f Dox::Formatter --order defined --tag dox --out spec/api_doc/v1/schemas/docs.json
-
render HTML with Redoc:
redoc-cli bundle -o public/api/docs/v2/docs.html spec/api_doc/v1/schemas/docs.json
It's recommendable to write a few rake tasks to make things easier. Here's an example:
namespace :dox do
desc 'Generate API documentation markdown'
task :json, [:version, :docs_path, :host] => :environment do |_, args|
require 'rspec/core/rake_task'
version = args[:version] || :v1
RSpec::Core::RakeTask.new(:api_spec) do |t|
t.pattern = "spec/requests/api/#{version}"
t.rspec_opts =
"-f Dox::Formatter --tag dox --order defined --out spec/docs/#{version}/apispec.json"
end
Rake::Task['api_spec'].invoke
end
task :html, [:version, :docs_path, :host] => :json do |_, args|
version = args[:version] || :v1
docs_path = args[:docs_path] || "api/#{version}/docs"
`yarn run redoc-cli bundle -o public/#{docs_path}/index.html spec/docs/#{version}/apispec.json`
end
task :open, [:version, :docs_path, :host] => :html do |_, args|
version = args[:version] || :v1
docs_path = args[:docs_path] || "api/#{version}/docs"
`open public/#{docs_path}/index.html`
end
end
You can render the HTML yourself with ReDoc:
You might experience some strange issues when generating the documentation. Here are a few examples of what we've encountered so far.
There seems to be a problem with rspec-rails versions 3.7 and later not automatically requiring the project's rails_helper.rb when run with the --format
flag.
To fix this issue, generate your documentation with --require rails_helper
:
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/infinum/dox. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
Dox is maintained and sponsored by Infinum.
The gem is available as open source under the terms of the MIT License.