Awesome
ReqresRspec
Gem generates API documentation from your integration tests written with rspec
.
No additional DSL needed. Beside covering rspec tests, documentation may be extended with API controller action comments in yardoc
style.
Documentation is generated in JSON, YAML, HTML, PDF formats.
Installation
1) Gem
Just add this gem to Gemfile
of your API Application
gem 'reqres_rspec', group: :test
And then execute:
$ bundle install
If necessary, add require "reqres_rspec"
to your spec/spec_helper.rb
file
2) PDF generator
Install prince
http://www.princexml.com/download/ . For MacOS installation commands are
wget http://www.princexml.com/download/prince-10r3-macosx.tar.gz
tar -xvf prince-10r3-macosx.tar.gz
cd prince-10r3-macosx
./install.sh
Usage
by default reqres_rspec
is not active (this may be configured!). To activate it, run rspec
with
REQRES_RSPEC=1 bundle exec rspec --order=defined
Documentation will be put into your application's /doc
folder
Upload to Amazon S3
Set up following environment variables
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_REQRES_BUCKET
Then run
REQRES_RSPEC=1 REQRES_UPLOAD=AmazonS3 bundle exec rspec --order=defined
Sample controller action
# @description creates Category from given parameters
# description text may be multiline
# @param category[title] required String Category title
# @param category[weight] in which order Category will be shown
# param text may also be multiline
def create
category = Category.new(create_category_params)
if category.save
render json: { category: category }.to_json, status: 201
else
render json: { errors: category.errors.full_messages }, status: 422
end
end
Description param text is started with @description
and may be multiline.
Each param text is started with @param
and first word will be param name, then optionally required
, then optionally type (Integer
, String
etc), and finally param description, which may be multiline as well.
Sample rspec test
it 'validates params', :skip_reqres do
...
end
context 'With valid params' do
it 'bakes pie' do
...
end
end
context 'With invalid params', :skip_reqres do
it 'returns errors' do
...
end
end
By default all examples will be added to docs. A context of examples (context
and describe
blocks) or any particular examples may be excluded from docs with option :skip_reqres
Doc will use full example description, as a title for each separate spec
If you want to group examples in another way, you can do something like:
describe 'Something', reqres_section: 'Foo' do
context 'valid params', reqres_title: 'Bakes Pie' do
it 'works' do
...
end
it 'tires baker', reqres_title: 'Tires baker' do
...
end
end
end
In this case all the reqres_sections
can be used for grouping collected data into section, and reqres_title
will become human readable titles:
Generates documentation example
Documentation is written in HTML format, which then converted to PDF. PDF files are textual, support search and have internal navigation links
Configuration
ReqresRspec.configure do |c|
c.templates_path = Rails.root.join('spec/support/reqres/templates') # Path to custom templates
c.output_path = 'some path' # by default it will use doc/reqres
c.formatters = %w(MyCustomFormatter) # List of custom formatters, these can be inherited from ReqresRspec::Formatters::HTML
c.title = 'My API Documentation' # Title for your documentation
c.amazon_s3 = {
credentials: {
access_key_id: ENV['AWS_ACCESS_KEY_ID'], # by default it will use AWS_ACCESS_KEY_ID env var
secret_access_key: ENV['AWS_SECRET_ACCESS_KEY'], # by default it will use AWS_SECRET_ACCESS_KEY env var
region: (ENV['AWS_REGION'] || 'us-east-1'),
},
bucket: ENV['AWS_REQRES_BUCKET'], # by default it will use AWS_REQRES_BUCKET env for bucket name
enabled: false # Enable upload (only with REQRES_UPLOAD env var set)
}
end
Custom Formatter example
class CustomAPIDoc < ReqresRspec::Formatters::HTML
private
def write
# Copy assets
%w(styles images components scripts).each do |folder|
FileUtils.cp_r(path(folder), output_path)
end
# Generate general pages
@pages = {
'index.html' => 'Introduction',
'authentication.html' => 'Authentication',
'filtering.html' => 'Filtering, Sorting and Pagination',
'locations.html' => 'Locations',
'files.html' => 'Files',
'external-ids.html' => 'External IDs',
}
@pages.each do |filename, _|
@current_page = filename
save filename, render("pages/#{filename}")
end
# Generate API pages
@records.each do |record|
@record = record
@current_page = @record[:filename]
save "#{record[:filename]}.html", render('spec.html.erb')
end
end
end
Future plans
-
Write documentation in YAML, JSON formats
-
Add configuration (folders with API specs, default generate spec for all examples, or opt-in generation)
-
Cover with tests
-
Remove dependency on
rails
-
Add demo for
Rails
,Rails API
,Sinatra
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
Push gem
Example:
gem build reqres_rspec.gemspec
gem push reqres_rspec-0.2.6.gem