Yardbird

Documentation generator that uses Yardoc as the parser. It's suitable for both Sinatra and Rails applications.

Installation

Install as a Rubygem:

sudo gem install yardbird

Then run:

$ yardbird

Usage

$ yardbird generate myproject/ -o docs.md

Yardoc extensions

Every API endpoint comment must start with @apidoc.

@category <label>

Specify the category — a logic grouping — that the endpoint belongs.

@path <path>

Specify the path to the endpoint.

@method <method>

Specify the method. (Deprecated: @http.)

@optional [<type>] <name> <description>

Specify optional parameter. May be repeated.

@required [<type>] <name> <description>

Specify required parameter. May be required.

@example <path and query>

Give example endpoint usage.

@status <code> <description>

Describe response status. May be repeated.

Example comment

# @apidoc
# Returns a list of all agents.
#
# @category Agents
# @path /api/v1/agents
# @http GET
# @required [boolean] featured Return featured agents only.
# @optional [integer] offset Return agents from the given offset.
# @optional ['yyyy-mm-ddThh:mm'] after Return all agents created after the given date.
# @status 403 If basic auth username is not 'api' or password is incorrect
# @status 400 If an invalid parameter is provided.
# @example /api/v1/agents?featured=true&offset=200&limit=100&before=2014-04-16&after=2014-01-01
#
get '/agents' do
  ...
end