Extend

apiDoc can be extended with your own parameters (if something is not available that you need). Look at lib/parsers/,
lib/workers/, and lib/filters/
directories in the apidoc/apidoc-core project for examples.
parser split the parameter data, worker processes additional functions with all found data and filter reduce the data to needed things.

Or fork the whole project and create a pull request to make apiDoc better.

Configuration (apidoc.json)

The optional apidoc.json in your projects root dir includes common information about your project like title, short description, version and configuration options like header / footer settings or template specific options.

In this example, a block named UserNotFoundError is defined with @apiDefine.
That block could be used many times with @apiUse UserNotFoundError.

In the generated output, both methods GET and PUT will have the complete UserNotFoundError documentation.

To define an inherit block, use apiDefine.
to reference a block, use apiUse.
apiGroup and apiPermission are use commands to, but in their context the not inherit parameters, only title and description (in combination with apiVersion).

Inheritation only works with 1 parent, more levels would make the inline code unreadable and changes really complex.

Versioning

A useful feature provided by apiDoc is the ability to maintain the documentation for all previous versions and the latest version of the API. This makes it possible to compare a methods version with its predecessor. Frontend Developer can thus simply see what have changed and update their code accordingly.

In order to avoid code bloat when API documentation changes over time, it is recommended to use a separate history file named _apidoc.js. Before you change your documentation block, copy the old documentation to to this file, apiDoc will include the historical information automatically.

Full example

apiDoc-Params

Structure parameter like:

@apiDefine

is used to define a reusable documentation block. This block can be included in normal api documentation blocks. Using @apiDefine allows you to better organize complex documentation and avoid duplicating recurrent blocks.

A defined block can have all params (like @apiParam), except other defined blocks.

@api

@api {method} path [title]

Required!

Without that indicator, apiDoc parser ignore the documentation block.

The only exception are documentation blocks defined by @apiDefine, they not required @api.

Information about the size of the variable.{string{..5}} a string that has max 5 chars.{string{2..5}} a string that has min. 2 chars and max 5 chars.{number{100-999}} a number between 100 and 999.

{type=allowedValues}optional

Information about allowed values of the variable.{string="small"} a string that can only contain the word "small" (a constant).{string="small","huge"} a string that can contain the words "small" or "huge".{number=1,2,3,99} a number with allowed values of 1, 2, 3 and 99.

Can be combined with size:{string {..5}="small","huge"} a string that has max 5 chars and only contain the words "small" or "huge".