Awesome
Had
Had is Hanami Api Documentation. Gem generates API documentation from your integration tests written with rspec
for Hanami.
This is fork of reqres_rspec
gem and worked implemantation for Hanami.
Installation
1) Gem
Just add this gem to Gemfile
of your API Application
gem 'had', group: :test
And then execute:
$ bundle install
If necessary, add require "had"
to your spec/spec_helper.rb
file
Usage
Before start you need to setup environment.
export APP_ROOT=/path/to/your/application
By default had
is not active (this may be configured!). To activate it, run rspec
with
HAD_RUN=1 bundle exec rspec --order=defined
Documentation will be put into your application's /doc
folder
Sample controller action
params do
required(:book).schema do
required(:author).filled(:str?) # This is params description
required(:title).filled(:str?) # Can be empty
end
end
# @description creates Category from given parameters
# description text may be multiline
# @param book[author] required String | You can use this params
# @param book[title] in which order | if you did't using dry-validation
# param text may also be multiline
def call(params)
# action code
end
Sample rspec test
it 'validates params', :skip_had do
...
end
context 'With valid params' do
it 'bakes pie' do
...
end
end
context 'With invalid params', :skip_had 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_had
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', had_section: 'Foo' do
context 'valid params', had_title: 'Bakes Pie' do
it 'works' do
...
end
it 'tires baker', had_title: 'Tires baker' do
...
end
end
end
Configuration
Had.configure do |c|
c.templates_path = './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 Had::Formatters::HTML
c.title = 'My API Documentation' # Title for your documentation
end
Custom Formatter example
class CustomAPIDoc < Had::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
- 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