RSpec API Doc Generator

Generate pretty API docs for your Rails APIs.

Check out a sample.

Changes

Please see the wiki for latest changes.

Installation

Add rspec_api_documentation to your Gemfile

gem 'rspec_api_documentation'

Bundle it!

$ bundle install

Set up specs.

$ mkdir spec/acceptance
$ vim spec/acceptance/orders_spec.rb

require 'rails_helper'
require 'rspec_api_documentation/dsl'

resource "Orders" do
  get "/orders" do
    example "Listing orders" do
      do_request

      expect(status).to eq 200
    end
  end
end

Generate the docs!

$ rake docs:generate
$ open doc/api/index.html

Viewers

Consider adding a viewer to enhance the generated documentation. By itself rspec_api_documentation will generate very simple HTML. All viewers use the generated JSON.

• Raddocs - Sinatra app
• Apitome - Rails engine

Gemfile

gem 'raddocs'

or 

gem 'apitome'

spec/spec_helper.rb

RspecApiDocumentation.configure do |config|
  config.format = :json
end

For both raddocs and apitome, start rails server. Then

open http://localhost:3000/docs for raddocs

or

http://localhost:3000/api/docs for apitome

Sample App

See the example folder for a sample Rails app that has been documented. The sample app demonstrates the :open_api format.

Example of spec file

  # spec/acceptance/orders_spec.rb
  require 'rails_helper'
  require 'rspec_api_documentation/dsl'
  resource 'Orders' do
    explanation "Orders resource"
    
    header "Content-Type", "application/json"

    get '/orders' do
      # This is manual way to describe complex parameters
      parameter :one_level_array, type: :array, items: {type: :string, enum: ['string1', 'string2']}, default: ['string1']
      parameter :two_level_array, type: :array, items: {type: :array, items: {type: :string}}
      
      let(:one_level_array) { ['string1', 'string2'] }
      let(:two_level_array) { [['123', '234'], ['111']] }

      # This is automatic way
      # It's possible because we extract parameters definitions from the values
      parameter :one_level_arr, with_example: true
      parameter :two_level_arr, with_example: true

      let(:one_level_arr) { ['value1', 'value2'] }
      let(:two_level_arr) { [[5.1, 3.0], [1.0, 4.5]] }

      context '200' do
        example_request 'Getting a list of orders' do
          expect(status).to eq(200)
        end
      end
    end

    put '/orders/:id' do

      with_options scope: :data, with_example: true do
        parameter :name, 'The order name', required: true
        parameter :amount
        parameter :description, 'The order description'
      end

      context "200" do
        let(:id) { 1 }

        example 'Update an order' do
          request = {
            data: {
              name: 'order',
              amount: 1,
              description: 'fast order'
            }
          }
          
          # It's also possible to extract types of parameters when you pass data through `do_request` method.
          do_request(request)
          
          expected_response = {
            data: {
              name: 'order',
              amount: 1,
              description: 'fast order'
            }
          }
          expect(status).to eq(200)
          expect(response_body).to eq(expected_response)
        end
      end

      context "400" do
        let(:id) { "a" }

        example_request 'Invalid request' do
          expect(status).to eq(400)
        end
      end
      
      context "404" do
        let(:id) { 0 }
        
        example_request 'Order is not found' do
          expect(status).to eq(404)
        end
      end
    end
  end

Configuration options

# Values listed are the default values
RspecApiDocumentation.configure do |config|
  # Set the application that Rack::Test uses
  config.app = Rails.application

  # Used to provide a configuration for the specification (supported only by 'open_api' format for now) 
  config.configurations_dir = Rails.root.join("doc", "configurations", "api")

  # Output folder
  # **WARNING*** All contents of the configured directory will be cleared, use a dedicated directory.
  config.docs_dir = Rails.root.join("doc", "api")

  # An array of output format(s).
  # Possible values are :json, :html, :combined_text, :combined_json,
  #   :json_iodocs, :textile, :markdown, :append_json, :slate,
  #   :api_blueprint, :open_api
  config.format = [:html]

  # Location of templates
  config.template_path = "inside of the gem"

  # Filter by example document type
  config.filter = :all

  # Filter by example document type
  config.exclusion_filter = nil

  # Used when adding a cURL output to the docs
  config.curl_host = nil

  # Used when adding a cURL output to the docs
  # Allows you to filter out headers that are not needed in the cURL request,
  # such as "Host" and "Cookie". Set as an array.
  config.curl_headers_to_filter = nil

  # By default, when these settings are nil, all headers are shown,
  # which is sometimes too chatty. Setting the parameters to an
  # array of headers will render *only* those headers.
  config.request_headers_to_include = nil
  config.response_headers_to_include = nil

  # By default examples and resources are ordered by description. Set to true keep
  # the source order.
  config.keep_source_order = false

  # Change the name of the API on index pages
  config.api_name = "API Documentation"
  
  # Change the description of the API on index pages
  config.api_explanation = "API Description"

  # Redefine what method the DSL thinks is the client
  # This is useful if you need to `let` your own client, most likely a model.
  config.client_method = :client

  # Change the IODocs writer protocol
  config.io_docs_protocol = "http"

  # You can define documentation groups as well. A group allows you generate multiple
  # sets of documentation.
  config.define_group :public do |config|
    # By default the group's doc_dir is a subfolder under the parent group, based
    # on the group's name.
    # **WARNING*** All contents of the configured directory will be cleared, use a dedicated directory.
    config.docs_dir = Rails.root.join("doc", "api", "public")

    # Change the filter to only include :public examples
    config.filter = :public
  end

  # Change how the post body is formatted by default, you can still override by `raw_post`
  # Can be :json, :xml, or a proc that will be passed the params
  config.request_body_formatter = Proc.new { |params| params }

  # Change how the response body is formatted by default
  # Is proc that will be called with the response_content_type & response_body
  # by default, a response body that is likely to be binary is replaced with the string
  # "[binary data]" regardless of the media type.  Otherwise, a response_content_type of `application/json` is pretty formatted.
  config.response_body_formatter = Proc.new { |response_content_type, response_body| response_body }

  # Change the embedded style for HTML output. This file will not be processed by
  # RspecApiDocumentation and should be plain CSS.
  config.html_embedded_css_file = nil

  # Removes the DSL method `status`, this is required if you have a parameter named status
  # In this case you can assert response status with `expect(response_status).to eq 200`
  config.disable_dsl_status!

  # Removes the DSL method `method`, this is required if you have a parameter named method
  config.disable_dsl_method!
end

Format

• json: Generates an index file and example files in JSON.
• html: Generates an index file and example files in HTML.
• combined_text: Generates a single file for each resource. Used by Raddocs for command line docs.
• combined_json: Generates a single file for all examples.
• json_iodocs: Generates I/O Docs style documentation.
• textile: Generates an index file and example files in Textile.
• markdown: Generates an index file and example files in Markdown.
• api_blueprint: Generates an index file and example files in APIBlueprint.
• append_json: Lets you selectively run specs without destroying current documentation. See section below.
• slate: Builds markdown files that can be used with Slate, a beautiful static documentation builder.
• open_api: Generates OpenAPI Specification (OAS) (Current supported version is 2.0). Can be used for Swagger-UI

append_json

This format cannot be run with other formats as they will delete the entire documentation folder upon each run. This format appends new examples to the index file, and writes all run examples in the correct folder.

Below is a rake task that allows this format to be used easily.

RSpec::Core::RakeTask.new('docs:generate:append', :spec_file) do |t, task_args|
  if spec_file = task_args[:spec_file]
    ENV["DOC_FORMAT"] = "append_json"
  end
  t.pattern    = spec_file || 'spec/acceptance/**/*_spec.rb'
  t.rspec_opts = ["--format RspecApiDocumentation::ApiFormatter"]
end

And in your spec/spec_helper.rb:

ENV["DOC_FORMAT"] ||= "json"

RspecApiDocumentation.configure do |config|
  config.format    = ENV["DOC_FORMAT"]
end

rake docs:generate:append[spec/acceptance/orders_spec.rb]

This will update the current index's examples to include any in the orders_spec.rb file. Any examples inside will be rewritten.

api_blueprint

This format (APIB) has additional functions:

• route: APIB groups URLs together and then below them are HTTP verbs.

  route "/orders", "Orders Collection" do
    get "Returns all orders" do
      # ...
    end
  
    delete "Deletes all orders" do
      # ...
    end
  end

  If you don't use route, then param in get(param) should be an URL as states in the rest of this documentation.

• attribute: APIB has attributes besides parameters. Use attributes exactly like you'd use parameter (see documentation below).

open_api

This format (OAS) has additional functions:

• authentication(type, value, opts = {}) (Security schema object)

  The values will be passed through header of the request. Option name has to be provided for apiKey.

  • authentication :basic, 'Basic Key'
  • authentication :apiKey, 'Api Key', name: 'API_AUTH', description: 'Some description'

  You could pass Symbol as value. In this case you need to define a let with the same name.

  authentication :apiKey, :api_key
  let(:api_key) { some_value } 
  

• route_summary(text) and route_description(text). (Operation object)

  These two simplest methods accept String. It will be used for route's summary and description.

• Several new options on parameter helper.

  • with_example: true. This option will adjust your example of the parameter with the passed value.
  • example: <value>. Will provide a example value for the parameter.
  • default: <value>. Will provide a default value for the parameter.
  • minimum: <integer>. Will setup upper limit for your parameter.
  • maximum: <integer>. Will setup lower limit for your parameter.
  • enum: [<value>, <value>, ..]. Will provide a pre-defined list of possible values for your parameter.
  • type: [:file, :array, :object, :boolean, :integer, :number, :string]. Will set a type for the parameter. Most of the type you don't need to provide this option manually. We extract types from values automatically.

You also can provide a configuration file in YAML or JSON format with some manual configs. The file should be placed in configurations_dir folder with the name open_api.yml or open_api.json. In this file you able to manually hide some endpoints/resources you want to hide from generated API specification but still want to test. It's also possible to pass almost everything to the specification builder manually.

Example of configuration file

swagger: '2.0'
info:
  title: OpenAPI App
  description: This is a sample server.
  termsOfService: 'http://open-api.io/terms/'
  contact:
    name: API Support
    url: 'http://www.open-api.io/support'
    email: support@open-api.io
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  version: 1.0.0
host: 'localhost:3000'
schemes:
  - http
  - https
consumes:
  - application/json
  - application/xml
produces:
  - application/json
  - application/xml
paths: 
  /orders:
    hide: true
  /instructions:
    hide: false
    get:
      description: This description came from configuration file
      hide: true

Example of spec file with :open_api format

  resource 'Orders' do
    explanation "Orders resource"
    
    authentication :apiKey, :api_key, description: 'Private key for API access', name: 'HEADER_KEY'
    header "Content-Type", "application/json"
    
    let(:api_key) { generate_api_key }

    get '/orders' do
      route_summary "This URL allows users to interact with all orders."
      route_description "Long description."

      # This is manual way to describe complex parameters
      parameter :one_level_array, type: :array, items: {type: :string, enum: ['string1', 'string2']}, default: ['string1']
      parameter :two_level_array, type: :array, items: {type: :array, items: {type: :string}}
      
      let(:one_level_array) { ['string1', 'string2'] }
      let(:two_level_array) { [['123', '234'], ['111']] }

      # This is automatic way
      # It's possible because we extract parameters definitions from the values
      parameter :one_level_arr, with_example: true
      parameter :two_level_arr, with_example: true

      let(:one_level_arr) { ['value1', 'value2'] }
      let(:two_level_arr) { [[5.1, 3.0], [1.0, 4.5]] }

      context '200' do
        example_request 'Getting a list of orders' do
          expect(status).to eq(200)
          expect(response_body).to eq(<response>)
        end
      end
    end

    put '/orders/:id' do
      route_summary "This is used to update orders."

      with_options scope: :data, with_example: true do
        parameter :name, 'The order name', required: true
        parameter :amount
        parameter :description, 'The order description'
      end

      context "200" do
        let(:id) { 1 }

        example 'Update an order' do
          request = {
            data: {
              name: 'order',
              amount: 1,
              description: 'fast order'
            }
          }
          
          # It's also possible to extract types of parameters when you pass data through `do_request` method.
          do_request(request)
          
          expected_response = {
            data: {
              name: 'order',
              amount: 1,
              description: 'fast order'
            }
          }
          expect(status).to eq(200)
          expect(response_body).to eq(<response>)
        end
      end

      context "400"