Getting started

Preface

All examples in this document use the Javadoc-Style (can be used in C#, Go, Dart, Java, JavaScript, PHP, TypeScript and all other Javadoc capable languages):

/**
 * This is a comment.
 */

For other languages use their specific multiline comment code:

CoffeeScript

###
This is a comment.
###

Erlang (% within the comment is optional)

%{
% This is a comment.
%}

Perl (Doxygen)

#**
# This is a comment.
#*

Python

"""
This is a comment.
"""

Ruby

=begin
This is a comment.
=end

Install

npm install apidoc -g

Run

apidoc -i myapp/ -o apidoc/ -t mytemplate/

Creates an apiDoc of all files within dir myapp/, uses template from dir mytemplate/ and put all output to dir apidoc/.

Without any parameter, apiDoc generate a documentation from all .cs .dart .erl .go .java .js .php .py .rb .ts files in current dir (incl. subdirs) and writes the output to ./doc/.

Command Line Interface

Show command line parameters:

apidoc -h

Important parameters:

Parameter Description
-f, --file-filters RegEx-Filter to select files that should be parsed (many -f can be used). Default .cs .dart .erl .go .java .js .php .py .rb .ts.

Example (parse only .js and .ts files):
apidoc -f ".*\\.js$" -f ".*\\.ts$"
-i, --input Input / source dirname. Location of your project files.

Example:
apidoc -i myapp/
-o, --output Output dirname. Location where to put to generated documentation.

Example:
apidoc -o apidoc/
-t, --template Use template for output files. You can create and use your own template.

Example:
apidoc -t mytemplate/

Template

apiDoc include a default template which uses handlebars, Bootstrap, RequireJS and jQuery for the output of the generated api_data.js and api_project.js as a html-page.

By default the generated apiDoc use a complex Template, which support

  • versioning: view different versions of your API
  • compare: view changes between two versions of your API

view default demo

Create your own

You can create your own template and use the apiDoc generated files api_data.js, api_project.js, or json only files api_data.json, api_project.json.

View the source on https://github.com/apidoc/apidoc/tree/master/template

Extend

apiDoc can be extended with own parameters (if you miss something). Look at the lib/plugins/ dir for examples. parser split the parameter data, worker processes additional functions with all found data and filter reduce the data to needed things.

Example usage: apidoc --parse-filters myFilter=pathToMyFilter/myFilter.js

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.

apidoc.json

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1",
}

If you use a package.json (e.g. in a node.js project), all apidoc.json settings can be done in package.json too, just add them under the "apidoc": { } parameter.

package.json

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "apidoc": {
    "title": "Custom apiDoc browser title",
    "url" : "https://api.github.com/v1",
  }
}

Settings for apidoc.json

Name Description
name Name of your project.
If no apidoc.json with the field exists, then apiDoc try to determine the the value from package.json.
version Version of your project.
If no apidoc.json with the field exists, then apiDoc try to determine the the value from package.json.
description Introduction of your project.
If no apidoc.json with the field exists, then apiDoc try to determine the the value from package.json.
title Browser title text.
url Prefix for api path (endpoints), e.g. https://api.github.com/v1
header
    title Navigation text for the included header.md file.
(watch Header / Footer)
    filename Filename (markdown-file) for the included header.md file.
footer
    title Navigation text for the included footer.md file.
    filename Filename (markdown-file) for the included footer.md file.

Template specific settings

The following settings are specific for the default template of apiDoc.

Name Type Description
template
    withCompare Boolean Enable comparison with older api versions. Default: true
    withGenerator Boolean Output the generator information at the footer. Default: true

Header / Footer

In your projects apidoc.json you can add a header and footer.

The title will be visible in the navigation. The filename should be a markdown textfile.

apidoc.json

{
  "header": {
    "title": "My own header title",
    "filename": "header.md"
  },
  "footer": {
    "title": "My own footer title",
    "filename": "footer.md"
  }
}

Examples

An introduction Presentation with a small example can be found at speakerdeck.com.

Basic

In this basic example we have a small project file and an apidoc.json.

View example output


apidoc.json

{
  "name": "example",
  "version": "0.1.0",
  "description": "A basic apiDoc example"
}

From apidoc.json apiDoc get the name, version and description of your project.
The file is optional (it depend on your template if the data is required).


example.js

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

A documentation block starts with /** and end with */.

This example describes a GET Method to request the User Information by the users id.

@api {get} /user/:id Request User information is required, without @api apiDoc ignores a documentation block.

@apiName is a unique name and should always be used.
Format: method + path (e.g. Get + User)

@apiGroup should always be used, under that name will this method be grouped.

All other fields are optional, look at their description under apiDoc-Params.

Inherit

Inherit mean, that you can define parts of your documentation that shall be used many times.

View example output


apidoc.json

{
  "name": "example-inherit",
  "version": "0.1.0",
  "description": "apiDoc inherit example"
}


example.js

/**
 * @apiDefineErrorStructure UserNotFoundError
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiErrorStructure UserNotFoundError
 */

/**
 * @api {put} /user/ Modify User information
 * @apiName PutUser
 * @apiGroup User
 *
 * @apiParam {Number} id          Users unique ID.
 * @apiParam {String} [firstname] Firstname of the User.
 * @apiParam {String} [lastname]  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *
 * @apiErrorStructure UserNotFoundError
 */

In this case a block named UserNotFoundError is defined with @apiDefineErrorStructure.
That block could be used many times with @apiErrorStructure UserNotFoundError.

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


Inherit define commands are apiDefineErrorStructure, apiDefinePermission, apiDefineStructure and apiDefineSuccessStructure.
Use names are apiErrorStructure, apiPermission, apiStructure and apiSuccessStructure.

At the moment inherit use only 1 parent, more levels would make the inline code unreadable and changes really complex.

Versioning

Nice feature is the keeping of previous defined documentation blocks. That makes it possible to compare a methods version with its predecessor. Frontend Developer can thus simply see what have changed and modify their code.

View example output

In the example, click top right on select box (the main version) and select Compare all with predecessor.

  • The main navigation mark all changed methods with a green bar.
  • Each method show the difference to its predecessor.
  • Green marks contents that were added (in this case title text changed and field registered was added).
  • Red marks contents that were removed.

You can change the main version (top right) to a previous version and compare older methods with their predecessor.


apidoc.json

{
  "name": "example-versioning",
  "version": "0.2.0",
  "description": "apiDoc versioning example"
}


So that your code not blow out with documentation blocks, i prefer to use a separate history file named _apidoc.js. Before you change your documentation block, copy the old block to to this file, that's all.

_apidoc.js

/**
 * @api {get} /user/:id Get User information
 * @apiVersion 0.1.0
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

example.js (your current project file)

/**
 * @api {get} /user/:id Get User information and Date of Registration.
 * @apiVersion 0.2.0
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname  Firstname of the User.
 * @apiSuccess {String} lastname   Lastname of the User.
 * @apiSuccess {Date}   registered Date of Registration.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

Important is to set the version with @apiVersion on every documentation block.


The version can be used on every block, also on inherit blocks. You don't have to change the version on an inherit block, the parser check automatically for the nearest predecessor.

apiDoc-Params

Structure Params like:

  • @apiDefineErrorStructure
  • @apiDefinePermission
  • @apiDefineStructure
  • @apiDefineSuccessStructure

are used to define a documentation block as a draft. This drafts can be included in normal api documentation blocks. With drafts you can separate complex or recurrent blocks.

A structure block can have all normal params (like @apiParam), except other structures, but you should e. g. use ErrorStructures for errors and SuccessStructures for success documentation blocks (for better overview).

@api

@api {method} path [title]

Required!

Without that indicator, apiDoc parser ignore the documentation block.

Except definition blocks like @apiDefineStructure, they not need @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
 */

@apiDefineErrorStructure

@apiDefineErrorStructure name

Defines a documentation block as a draft to be used in normal @api blocks.

Should be used to define Error Parameters, like @apiError, @apiErrorExample.

Usage: @apiDefineErrorStructure MyError

Name Description
name Unique name for the block.
Same name with different @apiVersion can be defined.

Example:

/**
 * @apiDefineErrorStructure MyError
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */

/**
 * @api {get} /user/:id
 * @apiErrorStructure MyError
 */

For more watch inherit example.

@apiDefineHeaderStructure

@apiDefineHeaderStructure name

Defines a documentation block as a draft to be used in normal @api blocks.

Should be used to define Header Parameters, like @apiHeader, @apiHeaderExample.

Similar operation as @apiDefineStructure.

Usage: @apiDefineHeaderStructure MyHeader

Name Description
name Unique name for the block.
Same name with different @apiVersion can be defined.

Example:

/**
 * @apiDefineHeaderStructure MyHeader
 * @apiHeader {String} firstname Firstname of the User.
 */

/**
 * @api {get} /user/:id
 * @apiHeaderStructure MyHeader
 */

For more watch inherit example.

@apiDefinePermission

@apiDefinePermission name [title]
                     [description]

Defines a permission as a draft to be used in normal @api blocks.

Usage: @apiDefinePermission admin

Name Description
name Unique name for the Permission.
Same name with different @apiVersion can be defined.
title optional A short title.
description optional Detailed Description start at the next line, multiple lines can be used.

Example:

/**
 * @apiDefinePermission admin Admin access rights needed. 
 * Optionally you can write here further Informations about the permission.
 */

/**
 * @api {get} /user/:id
 * @apiPermission admin
 */

@apiDefineStructure

@apiDefineStructure name

Defines a documentation block as a draft to be used in normal @api blocks.

Should be used to define normal Parameters, like @apiParam, @apiExample

Usage: @apiDefineStructure MyName

Name Description
name Unique name for the block.
Same name with different @apiVersion can be defined.

Example:

/**
 * @apiDefineStructure MyName
 * @apiParam {Number} id Users unique ID.
 */

/**
 * @api {get} /user/:id
 * @apiStructure MyName
 */

For more watch inherit example.

@apiDefineSuccessStructure

@apiDefineSuccessStructure name

Defines a documentation block as a draft to be used in normal @api blocks.

Should be used to define Success Parameters, like @apiSuccess, @apiSuccessExample.

Usage: @apiDefineSuccessStructure MySuccess

Name Description
name Unique name for the block.
Same name with different @apiVersion can be defined.

Example:

/**
 * @apiDefineSuccessStructure MySuccess
 * @apiSuccess {String} firstname Firstname of the User.
 */

/**
 * @api {get} /user/:id
 * @apiSuccessStructure MySuccess
 */

For more watch inherit example.

@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 simple name and describe it with @apiErrorTitle.
{type}optional Return type, e.g. {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), ...
field Return Identifier (returned error code).
descriptionoptional Description of the field.

Example:

/**
 * @api {get} /user/:id
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */

@apiErrorTitle

@apiErrorTitle (group) description

Replace the short group-name with a description

Global usage, use it once, no versioning. Optional.

Usage: @apiErrorTitle (MyGroup) This are the Parameters for MyGroup:

Name Description
(group) All errors will be grouped by this name.
description In documentation the short group-name will be replaced with the description.

Examples:

/**
 * @api {post} /user/
 *
 * @apiErrorTitle (401) 401 Unauthorized
 * @apiError (401) notAuthorizedError User not found.
 *
 * @apiErrorTitle (404) 404 Not Found
 * @apiError (404) notFoundError Data not found.
 *
 * @apiError (500) serverError apiErrorTitle is not needed.
 */

Example without @apiErrorTitle:
/**
 * @api {post} /user/
 * @apiError (401 Unauthorized) notAuthorizedError User not found.
 * @apiError (404 Not Found) notFoundError Data not found.
 * @apiError (500) serverError apiErrorTitle is not needed.
 */
 

@apiErrorExample

@apiErrorExample [title]
                 example

Example of an error return message, output as a pre-formatted code.

Usage: @apiErrorExample Error-Response:
This is an example.

Name Description
titleoptional Short title for the example.
example Detailed example, multilines capable.

Example:

/**
 * @api {get} /user/:id
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

@apiErrorStructure

@apiErrorStructure name

Include a with @apiDefineErrorStructure defined block. If used with @apiVersion the same or nearest predecessor will be included.

Usage: @apiErrorStructure MyError

Name Description
name Name of the defined error block.

Example:

/**
 * @api {get} /user/:id
 * @apiErrorStructure MyError
 */

@apiExample

@apiExample [title]
            example

Example for usage of an API method. Output as a pre-formatted code.

Usage: @apiExample Example usage:
This is an example.

Name Description
titleoptional Short title for the example.
example Detailed example, multilines capable.

Example:

/**
 * @api {get} /user/:id
 * @apiExample 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
 */

@apiGroupDescription

@apiGroupDescription text

Singleton usage at the moment. Use the tag only once for a group.

Detailed description of the Group, it will be in the documentation at the beginning of a group.

Usage: @apiGroupDescription Some information about the group

Name Description
text Multiline description text.

Example:

/**
 * @api {get} /user/:id
 * @apiGroup User
 * @apiGroupDescription The User-Group description.
 */

@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 simple name and describe it with @apiHeaderTitle.
{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.
=defaultValueoptional The parameters default value.
descriptionoptional Description of the field.

Examples:

/**
 * @api {get} /user/:id
 * @apiHeader {String} access-key Users unique access-key.
 */
 

@apiHeaderStructure

@apiHeaderStructure name

Include a with @apiDefineHeaderStructure defined block. If used with @apiVersion the same or nearest predecessor will be included.

Similar operation as @apiStructure.

Usage: @apiHeaderStructure MyHeader

Name Description
name Name of the defined header block.

Example:

/**
 * @api {get} /user/:id
 * @apiHeaderStructure MyHeader
 */

@apiHeaderTitle

@apiHeaderTitle (group) description

Replace the short group-name with a description

Global usage, use it once, no versioning. Optional.

Similar operation as @apiParamTitle.

Usage: @apiHeaderTitle (MyHeaderGroup) This are the Parameters for MyHeaderGroup:

Name Description
(group) All parameters will be grouped by this name.
description In documentation the short group-name will be replaced with the description.

Examples:

/**
 * @api {post} /user/
 *
 * @apiHeaderTitle (Auth) Parameters only for loggedin users:
 * @apiHeader (Auth) {String} key Users unique access-key.
 * @apiHeader (Auth) {String} system-key Access-key from external system.
 */

Example without @apiHeaderTitle:

/**
 * @api {post} /user/
 *
 * @apiHeader (Parameters only for loggedin users:) {String} key Users unique access-key.
 * @apiHeader (Parameters only for loggedin users:) {String} system-key Access-key from external system.
 */

@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
hintoptional 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.

Name Description
(group)optional All parameters will be grouped by this name.
Without a group, the default Parameter is set.
You can set a simple name and describe it with @apiParamTitle.
{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.
=defaultValueoptional The parameters default value.
descriptionoptional 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 {String} [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.
 */

@apiParamTitle

@apiParamTitle (group) description

Replace the short group-name with a description

Global usage, use it once, no versioning. Optional.

Usage: @apiParamTitle (MyGroup) This are the Parameters for MyGroup:

Name Description
(group) All parameters will be grouped by this name.
description In documentation the short group-name will be replaced with the description.

Examples:

/**
 * @api {post} /user/
 *
 * @apiParamTitle (Login) Parameters only for loggedin users:
 * @apiParam (Login) {String} newPassword New password.
 *
 * @apiParamTitle (Admin) Parameters only for admin users:
 * @apiParam (Admin) {String} newPassword New password.
 * @apiParam (Admin) {String} userId Change password of that user.
 */

Example without @apiParamTitle:

/**
 * @api {post} /user/
 *
 * @apiParam (Parameters only for loggedin users:) {String} newPassword New password.
 *
 * @apiParam (Parameters only for admin users:) {String} newPassword New password.
 * @apiParam (Parameters only for admin users:) {String} userId Change password of that user.
 */

@apiPermission

@apiPermission name

Outputs the permission name. If the name is defined with @apiDefinePermission 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
 */

@apiStructure

@apiStructure name

Include a with @apiDefineStructure defined block. If used with @apiVersion the same or nearest predecessor will be included.

Usage: @apiStructure MyStructure

Name Description
name Name of the defined block.

Example:

/**
 * @api {get} /user/:id
 * @apiStructure MyStructure
 */

@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 simple name and describe it with @apiSuccessTitle.
{type}optional Return type, e.g. {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), ...
field Return Identifier (returned success code).
descriptionoptional 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}  profile.age   Users age.
 * @apiSuccess {String}  profile.image Avatar-Image.
 */

Example with Array:

/**
 * @api {get} /users
 * @apiSuccess {Object[]} profiles       List of user profiles.
 * @apiSuccess {Number}   profiles.age   Users age.
 * @apiSuccess {String}   profiles.image Avatar-Image.
 */

@apiSuccessTitle

@apiSuccessTitle (group) description

Replace the short group-name with a description

Global usage, use it once, no versioning. Optional.

Usage: @apiSuccessTitle (MyGroup) This are the Parameters for MyGroup:

Name Description
(group) All success messages will be grouped by this name.
description In documentation the short group-name will be replaced with the description.

Examples:

/**
 * @api {post} /user/
 * @apiSuccessTitle (All) 200 - Data for all users:
 * @apiSuccess (All) id   The ID of a user.
 * @apiSuccess (All) name The name of a user.
 *
 * @apiSuccessTitle (LoggedIn) Data for LoggedIn users:
 * @apiSuccess (LoggedIn) id    The ID of a user.
 * @apiSuccess (LoggedIn) name  The name of a user.
 * @apiSuccess (LoggedIn) email E-Mail address of a user.
 */

Example without @apiErrorTitle:
/**
 * @api {post} /user/
 * @apiSuccess (200 - Data for all users:) id   The ID of a user.
 * @apiSuccess (200 - Data for all users:) name The name of a user.
 *
 * @apiSuccess (Data for LoggedIn users:) id    The ID of a user.
 * @apiSuccess (Data for LoggedIn users:) name  The name of a user.
 * @apiSuccess (Data for LoggedIn users:) email E-Mail address of a user.
 */
 

@apiSuccessExample

@apiSuccessExample [title]
                   example

Example of a success return message, output as a pre-formatted code.

Usage: @apiSuccessExample Success-Response:
This is an example.

Name Description
titleoptional Short title for the example.
example Detailed example, multilines capable.

Example:

/**
 * @api {get} /user/:id
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 */

@apiSuccessStructure

@apiSuccessStructure name

Include a with @apiDefineSuccessStructure defined block. If used with @apiVersion the same or nearest predecessor will be included.

Usage: @apiSuccessStructure MySuccess

Name Description
name Name of the defined success block.

Example:

/**
 * @api {get} /user/:id
 * @apiSuccessStructure MySuccess
 */

@apiVersion

@apiVersion version

Set the version of an documentation block. Version can also be defined in @apiDefineErrorStructure, @apiDefinePermission, @apiDefineStructure and @apiDefineSuccessStructure.

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.