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

See the wiki for additional setup. Setting up RSpec API Documentation

Raddocs

Also consider adding Raddocs as a viewer. It has much better HTML output than rspec_api_documentation.

gem 'raddocs'

Sample App

See the example folder for a sample Rails app that has been documented.

Configuration options

app - Set the application that Rack::Test uses, defaults to Rails.application
docs_dir - Output folder
format - An array of output format(s). Possible values are :json, :html
template_path - Location of templates
filter - Filter by example document type
exclusion_filter - Filter by example document type
curl_host - Used when adding a cURL output to the docs
keep_source_order - By default examples and resources are ordered by description. Set to true keep the source order.
api_name - Change the name of the API on index pages, default is "API Documentation"

Example Configuration

spec/spec_helper.rb

RspecApiDocumentation.configure do |config|
  config.docs_dir = Rails.root.join("app", "views", "pages")

  config.define_group :public do |config|
    config.docs_dir = Rails.root.join("public", "docs")
  end
end

Gotchas

rspec_api_documentation relies on a variable client to be the test client. Make sure you don't redefine this variable.
We make heavy use of RSpec metadata, you can actually use the entire gem without the DSL if you hand write the metadata.

Usage

resource "Account" do
  get "/accounts" do
    parameter :order, "Order of accounts"

    example_request "Get a list of all accounts" do
      status.should == 200
    end

    example "Get a list of all accounts in reverse order" do
      do_request(:order => "reverse")

      response_body.should == accounts.reverse
      status.should == 200
    end
  end

  get "/accounts/:id" do
    let(:account) { Factory(:account) }
    let(:id) { account.id }

    example "Get an account", :document => :public do
      do_request

      status.should == 200
    end
  end
end

smartlogic/rspec_api_documentation