Gemfile

spec/spec_helper.rb

Sample App

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

Configuration options

# Values listed are the default values
RspecApiDocumentation.configuredo|config|# Set the application that Rack::Test uses
config.app=Rails.application# Output folder
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
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=nilconfig.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"# 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:publicdo|config|# By default the group's doc_dir is a subfolder under the parent group, based
# on the group's name.
config.docs_dir=Rails.root.join("doc","api","public")# Change the filter to only include :public examples
config.filter=:publicend# 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 response_content_type of `application/json` are pretty formated.
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
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.

append_json: Lets you selectively run specs without destroying current documentation. See section below.

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.

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

Filtering and Exclusion

rspec_api_documentation lets you determine which examples get outputted into the final documentation.
All filtering is done via the :document metadata key.
You tag examples with either a single symbol or an array of symbols.
:document can also be false, which will make sure it does not get outputted.

resource"Account"doget"/accounts"doparameter:page,"Page to view"# default :document is :all
example"Get a list of all accounts"dodo_requeststatus.should==200end# Don't actually document this example, purely for testing purposes
example"Get a list on page 2",:document=>falsedodo_request(:page=>2)status.should==404end# With example_request, you can't change the :document
example_request"Get a list on page 3",:page=>3dostatus.should==404endendpost"/accounts"doparameter:email,"User email"example"Creating an account",:document=>:privatedodo_request(:email=>"eric@example.com")status.should==201endexample"Creating an account - errors",:document=>[:private,:developers]dodo_requeststatus.should==422endendend

# All documents will be generated into the top folder, :document => false
# examples will never be generated.
RspecApiDocumentation.configuredo|config|# Exclude only document examples marked as 'private'
config.define_group:non_privatedo|config|config.exclusion_filter=:privateend# Only document examples marked as 'public'
config.define_group:publicdo|config|config.filter=:publicend# Only document examples marked as 'developer'
config.define_group:developersdo|config|config.filter=:developersendend

DSL

Require the DSL

At the beginning of each acceptance/*_spec.rb file, make sure to require the following to pull in the DSL definitions:

require'rspec_api_documentation/dsl'

Example Group Methods

resource

Create a set of documentation examples that go together. Acts as a describe block.

get, head, post, put, delete, patch

The method that will be sent along with the url.

resource"Orders"dopost"/orders"doendget"/orders"doendhead"/orders"doendput"/orders/:id"dolet(:id){order.id}example"Get an order"dopath.should=="/orders/1"# `:id` is replaced with the value of `id`
endenddelete"/orders/:id"doendpatch"/orders/:id"doendend

example

This is just RSpec's built in example method, we hook into the metadata surrounding it. it could also be used.

parameter

This method takes the parameter name, a description, and an optional hash of extra metadata that can be displayed in Raddocs as extra columns. If a method with the parameter name exists, e.g. a let, it will send the returned value up to the server as URL encoded data.

Special values:

:required => true Will display a red '*' to show it's required

:scope => :the_scope Will scope parameters in the hash, scoping can be nested. See example

The value of scoped parameters can be set with both scoped (let(:order_item_item_id)) and unscoped (let(:item_id)) methods. It always searches for the scoped method first and falls back to the unscoped method.

raw_post

You can completely override what gets sent as parameters by let-ing raw_post.

resource"Orders"doheader"Content-Type","application/json"parameter:namelet(:name){"My Order"}post"/orders"dolet(:raw_post){params.to_json}example_request"Create new order"do# params get sent as JSON
endendend

Rake Task

The gem contains a Railtie that defines a rake task for generating docs easily with Rails.
It loads all files in spec/acceptance/**/*_spec.rb.

Uploading a file

For an example on uploading a file see examples/spec/acceptance/upload_spec.rb.

Gotchas

rspec_api_documentation relies on a variable client to be the test client. If you define your own client please configure rspec_api_documentation to use another one, see Configuration above.

We make heavy use of RSpec metadata, you can actually use the entire gem without the DSL if you hand write the metadata.

You must use response_body, status, response_content_type, etc. to access data from the last response. You will not be able to use response.body or response.status as the response object will not be created.