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.
Usage: @api {get} /user/:id Users unique ID.
Name Description
method
Request method name: DELETE, GET, POST, PUT, … More info Wikipedia HTTP-Request_methods
path Request Path.
title
optional
A short title. (used for navigation and article header)
Example:
/** * @api {get} /user/:id */
@apiBody
@apiBody [{type}] [field=defaultValue] [description]
Describe the request body passed to your API-Method.
Usage: @apiBody {type} {key: value}
Name Description
{type}
optional
Parameter type, e.g. {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), …
{type{size}}
optional
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”.
field
Fieldname.
[field]
Fieldname with brackets define the Variable as optional.
field[nestedField]
Mandatory nested field.
=defaultValue
optional
The parameters default value.
description
optional
Description of the field.
Examples:
/** * @api {get} /user/:id * @apiParam {Number} id Users unique ID. */ /** * @api {post} /user/ * @apiParam {String} [firstname] Optional Firstname of the User. * @apiParam {String} lastname Mandatory Lastname. * @apiParam {String} country="DE" Mandatory with default value "DE". * @apiParam {Number} [age=18] Optional Age with default 18. * * @apiParam (Login) {String} pass Only logged in users can post this. * In generated documentation a separate * "Login" Block will be generated. * * @apiParam {Object} [address] Optional nested address object. * @apiParam {String} [address[street]] Optional street and number. * @apiParam {String} [address[zip]] Optional zip code. * @apiParam {String} [address[city]] Optional city. */
@apiDefine
@apiDefine name [title] [description]
Defines a documentation block to be embedded within @api blocks or in an api function like @apiPermission.
@apiDefine can only be used once per block
By using @apiUse a defined block will be imported, or with the name the title and description will be used.
Usage: @apiDefine MyError
Name Description
name
Unique name for the block / value. Same name with different @apiVersion can be defined.
title
optional
A short title. Only used for named functions like @apiPermission or @apiParam (name).
description
optional
Detailed Description start at the next line, multiple lines can be used. Only used for named functions like @apiPermission.
Example:
/** * @apiDefine MyError */ /** * @api {get} /user/:id * @apiUse MyError */ /** * @apiDefine admin User access only * This optional description belong to to the group admin. */ /** * @api {get} /user/:id * @apiPermission admin */
For more details, see inherit example.
@apiDeprecated
@apiDeprecated [text]
Mark an API Method as deprecated
Usage: @apiDeprecated use now (#Group:Name).
Name Description
text Multiline text.
Example:
/** * @apiDeprecated */ /** * @apiDeprecated use now (#Group:Name). * * Example: to set a link to the GetDetails method of your group User * write (#User:GetDetails) */
@apiDescription
@apiDescription text
Detailed description of the API Method.
Usage: @apiDescription This is the Description.
Name Description
text Multiline description text.
Example:
/** * @apiDescription This is the Description. * It is multiline capable. * * Last line of Description. */
@apiError
@apiError [(group)] [{type}] field [description]
Error return Parameter.
Usage: @apiError UserNotFound
Name Description
(group)
optional
All parameters will be grouped by this name. Without a group, the default Error 4xx is set. You can set a title and description with @apiDefine.
{type}
optional
Return type, e.g. {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), …
field
Return Identifier (returned error code).
description
optional
Description of the field.
Example:
/** * @api {get} /user/:id */
@apiErrorExample
@apiErrorExample [{type}] [title] example
Example of an error return message, output as a pre-formatted code.
Usage: @apiErrorExample {json} Error-Response: This is an example.
Name Description
type
optional
Response format.
title
optional
Short title for the example.
example
Detailed example, multilines capable.
Example:
/** * @api {get} /user/:id * @apiErrorExample {json} Error-Response: * HTTP/1.1 404 Not Found * { * "error": "UserNotFound" * } */
@apiExample
@apiExample [{type}] title example
Example for usage of an API method. Output as a pre-formatted code.
Use it for a complete example at the beginning of the description of an endpoint.
Usage: @apiExample {js} Example usage: This is an example.
Name Description
type
optional
Code language.
title
Short title for the example.
example
Detailed example, multilines capable.
Example:
/** * @api {get} /user/:id * @apiExample {curl} Example usage: * curl -i http://localhost/user/4711 */
@apiGroup
@apiGroup name
Should always be used.
Defines to which group the method documentation block belongs. Groups will be used for the Main-Navigation in the generated output. Structure definition not need @apiGroup.
Usage: @apiGroup User
Name Description
name
Name of the group. Also used as navigation title.
Example:
/** * @api {get} /user/:id * @apiGroup User */
@apiHeader
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
Describe a parameter passed to you API-Header e.g. for Authorization.
Similar operation as @apiParam, only the output is above the parameters.
Usage: @apiHeader (MyHeaderGroup) {String} authorization Authorization value.
Name Description
(group)
optional
All parameters will be grouped by this name. Without a group, the default Parameter is set. You can set a title and description with @apiDefine.
{type}
optional
Parameter type, e.g. {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), …
field
Variablename.
[field]
Fieldname with brackets define the Variable as optional.
=defaultValue
optional
The parameters default value.
description
optional
Description of the field.
Examples:
/** * @api {get} /user/:id * @apiHeader {String} access-key Users unique access-key. */
@apiHeaderExample
@apiHeaderExample [{type}] [title] example
Parameter request example.
Usage: @apiHeaderExample {json} Request-Example: { "content": "This is an example content" }
Name Description
type
optional
Request format.
title
optional
Short title for the example.
example
Detailed example, multilines capable.
Example:
/** * @api {get} /user/:id * @apiHeaderExample {json} Header-Example: * { * "Accept-Encoding": "Accept-Encoding: gzip, deflate" * } */
@apiIgnore
@apiIgnore [hint]
Place it on top of a block.
A block with @apiIgnore will not be parsed. It is usefull, if you leave outdated or not finished Methods in your source code and you don’t want to publish it into the documentation.
Usage: @apiIgnore Not finished Method
Name Description
hint
optional
Short information why this block should be ignored.
Example:
/** * @apiIgnore Not finished Method * @api {get} /user/:id */
@apiName
@apiName name
Should always be used.
Defines the name of the method documentation block. Names will be used for the Sub-Navigation in the generated output. Structure definition not need @apiName.
Usage: @apiName GetUser
Name Description
name
Unique name of the method. Same name with different @apiVersion can be defined. Format: method + path (e.g. Get + User), only a proposal, you can name as you want. Also used as navigation title.
Example:
/** * @api {get} /user/:id * @apiName GetUser */
@apiParam
@apiParam [(group)] [{type}] [field=defaultValue] [description]
Describe a parameter passed to you API-Method.
Usage: @apiParam (MyGroup) {Number} id Users unique ID.
For nested parameters, use square bracket notation ([]).
Name Description
(group)
optional
All parameters will be grouped by this name. Without a group, the default Parameter is set. You can set a title and description with @apiDefine.
{type}
optional
Parameter type, e.g. {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), …
{type{size}}
optional
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”.
field
Fieldname.
[field]
Fieldname with brackets define the Variable as optional.
field[nestedField]
Mandatory nested field.
=defaultValue
optional
The parameters default value.
description
optional
Description of the field.
Examples:
/** * @api {get} /user/:id * @apiParam {Number} id Users unique ID. */ /** * @api {post} /user/ * @apiParam {String} [firstname] Optional Firstname of the User. * @apiParam {String} lastname Mandatory Lastname. * @apiParam {String} country="DE" Mandatory with default value "DE". * @apiParam {Number} [age=18] Optional Age with default 18. * * @apiParam (Login) {String} pass Only logged in users can post this. * In generated documentation a separate * "Login" Block will be generated. * * @apiParam {Object} [address] Optional nested address object. * @apiParam {String} [address[street]] Optional street and number. * @apiParam {String} [address[zip]] Optional zip code. * @apiParam {String} [address[city]] Optional city. */
@apiParamExample
@apiParamExample [{type}] [title] example
Parameter request example.
Usage: @apiParamExample {json} Request-Example: { "content": "This is an example content" }
Name Description
type
optional
Request format.
title
optional
Short title for the example.
example
Detailed example, multilines capable.
Example:
/** * @api {get} /user/:id * @apiParamExample {json} Request-Example: * { * "id": 4711 * } */
@apiPermission
@apiPermission name
Outputs the permission name. If the name is defined with @apiDefine the generated documentation include the additional title and description.
Usage: @apiPermission admin
Name Description
name
Unique name of the permission.
Example:
/** * @api {get} /user/:id * @apiPermission none */
@apiPrivate
@apiPrivate
Defines an API as being private to allow the creation of two API specification documents: one that excludes the private APIs and one that includes them.
Usage: @apiPrivate
Example:
/** * @api {get} /user/:id * @apiPrivate */
@apiBody
@apiQuery [{type}] [field=defaultValue] [description]
Describe a query parameter passed to your API-Method.
Usage: @apiQuery {Number} id Users unique ID.
Name Description
{type}
optional
Parameter type, e.g. {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), …
{type{size}}
optional
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”.
field
Fieldname.
[field]
Fieldname with brackets define the Variable as optional.
field[nestedField]
Mandatory nested field.
=defaultValue
optional
The parameters default value.
description
optional
Description of the field.
Examples:
/** * @api {get} /user/:id * @apiQuery admin */
@apiSampleRequest
@apiSampleRequest url
Use this parameter in conjunction with the chúng tôi configuration parameter sampleUrl.
If sampleUrl is set, all methods will have the api test form (the endpoint from @api will be appended).Without sampleUrl only methods with @apiSampleRequest will have a form.
if @apiSampleRequest url is set in a method block, this url will be used for the request (it overrides sampleUrl when it starts with http).
If sampleUrl is set and you don’t want a method with a test form, then add @apiSampleRequest off to the documentation block.
Usage: @apiSampleRequest http://test.github.com
Name Description
url
Url to your test api server.
Overwrite the configuration parameter sampleUrl and append @api url: @apiSampleRequest http://www.example.com
Prefix the @api url: @apiSampleRequest /my_test_path
Disable api test if configuration parameter sampleUrl is set: @apiSampleRequest off
Examples:
This will send the api request to http://api.github.com/user/:id
Configuration parameter sampleUrl: "http://api.github.com" /** * @api {get} /user/:id */
This will send the api request to http://test.github.com/some_path/user/:id It overwrites sampleUrl.
Configuration parameter sampleUrl: "http://api.github.com" /** * @api {get} /user/:id * @apiSampleRequest http://test.github.com/some_path/ */
This will send the api request to http://api.github.com/test/user/:id It extends sampleUrl.
Configuration parameter sampleUrl: "http://api.github.com" /** * @api {get} /user/:id * @apiSampleRequest /test */
This will disable the api request for this api-method.
Configuration parameter sampleUrl: "http://api.github.com" /** * @api {get} /user/:id * @apiSampleRequest off */
This will send the api request to http://api.github.com/some_path/user/:id It activates the request for this method only, because sampleUrl is not set.
Configuration parameter sampleUrl is not set /** * @api {get} /user/:id * @apiSampleRequest http://api.github.com/some_path/ */
@apiSuccess
@apiSuccess [(group)] [{type}] field [description]
Success return Parameter.
Usage: @apiSuccess {String} firstname Firstname of the User.
Name Description
(group)
optional
All parameters will be grouped by this name. Without a group, the default Success 200 is set. You can set a title and description with @apiDefine.
{type}
optional
Return type, e.g. {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), …
field
Return Identifier (returned success code).
description
optional
Description of the field.
Example:
/** * @api {get} /user/:id * @apiSuccess {String} firstname Firstname of the User. * @apiSuccess {String} lastname Lastname of the User. */
Example with (group), more group-examples at @apiSuccessTitle:
/** * @api {get} /user/:id * @apiSuccess (200) {String} firstname Firstname of the User. * @apiSuccess (200) {String} lastname Lastname of the User. */
Example with Object:
/** * @api {get} /user/:id * @apiSuccess {Boolean} active Specify if the account is active. * @apiSuccess {Object} profile User profile information. * @apiSuccess {Number} chúng tôi Users age. * @apiSuccess {String} profile.image Avatar-Image. */
Example with Array:
/** * @api {get} /users * @apiSuccess {Object[]} profiles List of user profiles. * @apiSuccess {Number} chúng tôi Users age. * @apiSuccess {String} profiles.image Avatar-Image. */
@apiSuccessExample
@apiSuccessExample [{type}] [title] example
Example of a success return message, output as a pre-formatted code.
Usage: @apiSuccessExample {json} Success-Response: { "content": "This is an example content" }
Name Description
type
optional
Response format.
title
optional
Short title for the example.
example
Detailed example, multilines capable.
Example:
/** * @api {get} /user/:id * @apiSuccessExample {json} Success-Response: * HTTP/1.1 200 OK * { * "firstname": "John", * "lastname": "Doe" * } */
@apiUse
@apiUse name
Include a with @apiDefine defined block. If used with @apiVersion the same or nearest predecessor will be included.
Usage: @apiUse MySuccess
Name Description
name
Name of the defined block.
Example:
/** * @apiDefine MySuccess * @apiSuccess {string} firstname The users firstname. * @apiSuccess {number} age The users age. */ /** * @api {get} /user/:id * @apiUse MySuccess */
@apiVersion
@apiVersion version
Set the version of an documentation block. Version can also be used in @apiDefine.
Blocks with same group and name, but different versions can be compared in the generated output, so you or a frontend developer can retrace what changes in the API since the last version.
Usage: @apiVersion 1.6.2
Name Description
version
Simple versioning supported (major.minor.patch). More info on Semantic Versioning Specification (SemVer).
Example:
/** * @api {get} /user/:id * @apiVersion 1.6.2 */
For more watch versioning example.