Autodoc

Auto-generate JSON API documents from your request-specs.

Installation

gem "autodoc", group: :test

Usage

All request-specs tagged with :autodoc will be auto-documented.
You must include a HTTP method and request path in the example description.

$ AUTODOC=1 rspec

# spec/requests/recipes_spec.rb
describe "Recipes" do
  let(:params) do
    { name: "alice", type: 1 }
  end

  describe "POST /recipes", autodoc: true do
    it "creates a new recipe" do
      post "/recipes.json", params
      response.status.should == 201
    end
  end
end

and the following document is generated in doc/recipes.md.

## POST /recipes
Creates a new recipe

```
POST /recipes
```

### parameters
* `name` string (required)
* `type` integer

### response
```
Status: 201
location: http://www.example.com/recipes/1
response: 
{
  "created_at" => "2013-06-07T08:28:35Z",
          "id" => 1,
        "name" => "alice",
        "type" => 1,
  "updated_at" => "2013-06-07T08:28:35Z"
}
```

Custom template

You can customize autodoc's template (Example).
Here are avilable variables:

• description
• example
• method
• parameters_section
• path
• request
• request_body_section
• response
• response_body
• response_headers
• response_status

Example

Autodoc.configuration.template = <<-EOF
  ## <%= method %> <%= path %>
  <%= description %>
  <%= parameters_section %>
  ### request
  ```
  <%= method %> <%= path %>
  ```
  <%= request_body_section %>
  ### response
  ```ruby
  Status: <%= response_status %><%= response_headers %>
  response: <%= response_body %>
  ```

EOF