Deprecated apiDoc-Params

Please use only current params.

@apiDefineErrorStructure

Deprecated ! Use @apiDefine

@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
 */

@apiDefineHeaderStructure

Deprecated ! Use @apiDefine

@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
 */

@apiDefinePermission

Deprecated ! Use @apiDefine

@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

Deprecated ! Use @apiDefine

@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
 */

@apiDefineSuccessStructure

Deprecated ! Use @apiDefine

@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
 */

@apiErrorStructure

Deprecated ! Use @apiUse

@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
 */

@apiErrorTitle

Deprecated ! Use @apiDefine

@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.
 */

@apiGroupDescription

Deprecated ! Use @apiDefine

@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.
 */

@apiHeaderStructure

Deprecated ! Use @apiUse

@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

Deprecated ! Use @apiDefine

@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.
 */

@apiParamTitle

Deprecated ! Use @apiDefine

@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.
 */

@apiStructure

Deprecated ! Use @apiUse

@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
 */

@apiSuccessStructure

Deprecated ! Use @apiUse

@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
 */

@apiSuccessTitle

Deprecated ! Use @apiDefine

@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.
 */
development is supported by inveris • hosted on GitHub • distributed over npm