Auto-generate API docs from your RSpec tests!
Turn something like
it 'retrievs the patients medications' do
retrieve_medications
expect(JSON.parse(response.body).length).to eql 1
expect(response).to have_http_status(:ok)
end
with simple annotations to your Rspec tests into:
See the full demo here from the example app with RSpec tests
Add this line to your application's Gemfile:
gem 'rspec-api-blueprint-formatter'
And then execute:
$ bundle
Or install it yourself as:
$ gem install rspec-api-blueprint-formatter
RSpec APIBlueprint Formatter not surprisingly generates output that conforms to the APIBlueprint spec. RSpec APIBlueprint Formatter makes some simplifying assumption and obviously falls short of manually crafted API docs. However, this can be a very efficient way to give your API consumers an easy to browse reference with basically 0 costs.
Effectively what the RSpec APIBlueprint Formatter will do is render tests you tag with :apidoc
with their request parameters and response body and status. You will need to also tag your tests with (usually in parent context/describe blocks):
resource_group: 'Resource Group Name',
resource: 'Resource Name [/path/to/resouce]',
action: 'Retrieve list of resource [HTTP_VERB]'
action_description: 'Some accurate, verbose description of the action'
action_parameters: {parameter: { options: {} } }
There are some additional restrictions:
- the
/path/to/resource
has to be unique across resources - the
HTTP_VERB
has to be unique within a resource
You use the formatter by specifying the -f
flag rspec spec -f ApiBlueprint
and it should print out the tests result in the APIBlueprint format. You can then use a renderer such as Aglio to turn the APIBlueprint format into a browsable HTML representation. It is recommended to create a rake task a la:
task generate_api_docs: :environment do
`rspec spec --tag apidoc -f ApiBlueprint --out spec/apispec.md`
`aglio -i spec/apispec.md -o spec/apispec.html`
end
By default, the Request parameters are printed out as the given parameters in the specs. You can add more information about them by using the action_parameters
metadata. The formatter supports most of the options for the API Blueprint URL parameters. A few examples below:
Spec - general:
let (:action_parameters) do
{
id: {description: 'Id of a post'}
}
end
RSpec.describe 'POST /do_something', action_parameters: action_parameters, resource_group: 'Resources', resource: 'Resource', action: 'Do something', action_description: 'Do something' do
end
Generates:
+ Parameters
+ id - Id of a post.
Spec:
let (:action_parameters) do
{
id: {description: 'Id of a post', type: :number}
}
end
Generates:
+ Parameters
+ id (number) - Id of a post.
Spec:
let (:action_parameters) do
{
id: {description: 'Id of a post', type: :number, optional: true, example: 1001}
}
end
Generates:
+ Parameters
+ id: `1001` (number, optional) - Id of a post.
Spec:
let (:action_parameters) do
{
id: {description: 'Id of a post', type: :number, optional: true, default: 20, example: 1001}
}
end
Generates:
+ Parameters
+ id: `1001` (number, optional) - Id of a post.
+ Default: `20`
Spec:
let (:action_parameters) do
{
id: {description: 'Id of a post', type: 'enum[string]', members: %w(A B C)}
}
end
Generates:
+ Parameters
+ id (enum[string])
Id of a Post
+ Members
+ `A`
+ `B`
+ `C`
<example value>
is not supported because it doesn't make sense with RSpec generated response bodies (already some example values there).required
flag is not supported - it is the default anyway.
Bug reports and pull requests are welcome on GitHub at https://github.com/nambrot/rspec-api-blueprint-formatter. 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.
The gem is available as open source under the terms of the MIT License.