apidoc-md

APIDoc-MD

Generate API documentation for your README from comments in your source-code. Uses apiDoc.

Usage

• add comments of the following format to routes in your codebase:

/**
 * @api {get} /stripe/:id fetch stripe customer
 * @apiName GetCustomer
 * @apiGroup Stripe
 *
 * @apiParam {String} id a username.
 *
 * @apiSuccess {String} status of paid stripe subscription.
 * @apiSuccess {Boolean} expired is the user's license expired.
 * @apiSuccess {String} email email associated with stripe subscription.
 * @apiSuccess {Integer} next_billing_date when will we next charge the card.
 * @apiSuccess {Integer} next_billing_amount how much will we next charge you.
 * @apiSuccess {Object} card object representing the user's credit-card
 *
 * @apiError CustomerNotFound a customer for this npm user does not yet exist.
 */
 function myAwesomeHandler() {}

• rename your README.md to README.md.mustache
• add the following template code to README.md.mustache

{{#each api}}
## {{@key}}

{{#each this}}
### {{type}} {{url}}

{{title}}

{{#each parameters}}
{{#if @first}}**Parameters**

{{/if}}
* **`{{{type}}}` {{field}}:** {{{description}}}
{{#if @last}}

{{/if}}
{{/each}}
{{#each success}}
{{#if @first}}**Response**

{{/if}}
* **`{{{type}}}` {{field}}:** {{{description}}}
{{#if @last}}

{{/if}}
{{/each}}
{{#each error}}
{{#if @first}}**Error**

{{/if}}
* **{{field}}:** {{{description}}}
{{#if @last}}

{{/if}}
{{/each}}
{{/each}}
{{/each}}

• add a script to your package.json that looks something like this.

{
  "scripts": {
    "build-docs": "apidoc-md generate"
  }
}