DSL

require's

At the beginning of each acceptance/*_spec.rb file, add these requires to pull in spec_helper and the DSL definitions:

require 'spec_helper'
require 'rspec_api_documentation/dsl'

example

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

This test describes an Orders resource that supports the HTTP POST verb. The test defines a name parameter. There is one example, which creates an Order with the name parameter bound to "My Order." When this example is run, the document orders/creating_an_order.html will be generated.

resource "Orders" do
  parameter :name

  let(:name) { "My Order" }

  post "/orders" do
    example "Creating an order" do
      do_request
      # make assertions on last_response
    end
  end
end

example_request

The same as example, except it does the request as the first step. Only assertions are required in the block. You can also pass it a hash to be sent to do_request.

resource "Orders" do
  parameter :name

  let(:name) { "My Order" }

  post "/orders" do
    example_request "Creating an order", :name => "Other name" do
      # make assertions on last_response
    end
  end
end

Example Group Methods

resource

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

resource "Orders" do
end

get, post, put, delete

The method that will be sent along with the url. The following example will create a post to /orders.

resource "Orders" do
  parameter :name

  let(:name) { "My Order" }

  post "/orders" do
  end
end

parameter

List a parameter on the outputted documentation. Also will send a let() variable via post if the name matches. In the following example the post data would be:

{ :name => "My Order" }

resource "Orders" do
  parameter :name

  let(:name) { "My Order" }
end

required_parameters

This lists parameters on the outputted documentation as required.

resource "Orders" do
  parameter :id
  required_parameters :id
end

scope_parameters

This scopes parameters that are sent underneath a key. In the following example the post data would be:

{ :order => { :name => "My Order" } }

resource "Orders" do
  parameter :name
  scope_parameters :order, [:name]

  let(:name) { "My Order" }
end

callback

This is complicated. See https://www.relishapp.com/zipmark/rspec-api-documentation/docs/document-callbacks

trigger_callback

Pass this method a block which, when evaluated, will cause the application to make a request to callback_url.

Example methods

callback_url

Defines the destination of the callback.

For an example, see: https://www.relishapp.com/zipmark/rspec-api-documentation/docs/document-callbacks

client

Returns the test client which makes requests and documents the responses. You can override client as long as it conforms to a simple interface.

do_callback

This will evaluate the block passed to trigger_callback, which should cause the application under test to make a callback request.

do_request

Sends the request to the app.

no_doc

If you wish to make a request via the client that should not be included in your documentation, do it inside of a no_doc block.

resource "Orders" do
  get "/" do
    example_request "Getting the root" do
      no_doc do
        client.get("/another_request")
      end
    end
  end
end

params

Get a hash of parameters that will be sent. In the following example the params hash would be:

{ :name => "My Order" }

resource "Orders" do
  parameter :name

  let(:name) { "My Order" }
end

response_body

Returns a string containing the response body from the previous request.

response_headers

Returns a hash of the response headers from the previous request.

status, response_status

Returns the numeric status code from the response, eg. 200. response_status is an alias to status because status is commonly a parameter.

query_string

Data that will be sent as a query string instead of post data. Used in GET requests. In the following example the request will be GET /orders?name=My+Order.

resource "Orders" do
  parameter :name

  let(:name) { "My Order" }

  get "/orders" do
  end
end