Project

had

0.0
No release in over 3 years
Low commit activity in last 3 years
Had is Hanami Api Documentation gem. This gem generates API documentation for integration tests written with RSpec for Hanami
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
 Project Readme

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
  1. Fork it
  2. Create your feature branch (git checkout -b my_new_feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my_new_feature)
  5. Create new Pull Request