tessl/npm-apidoc

RESTful web API Documentation Generator that creates beautiful, interactive documentation from specially formatted comments in source code

—

Pending

Overview

Eval results

Files

Comment Tag System

Name: tessl/npm-apidoc
Author: tessl

Complete reference for all supported API documentation tags that can be used in source code comments to generate documentation. These tags follow a consistent syntax and can be combined to create comprehensive API documentation.

Core API Tags

@api

@api {method} path [title]

Defines an API endpoint with HTTP method and URL path.

Parameters:

method: HTTP method (get, post, put, patch, delete, head, options)
path: URL path with optional parameters (e.g., /users/:id)
title: Optional human-readable title

Example:

/**
 * @api {get} /users/:id Get User Information
 * @api {post} /users Create New User
 * @api {put} /users/:id Update User
 * @api {delete} /users/:id Delete User
 */

@apiName

@apiName name

Unique identifier for the API endpoint, used for internal referencing and linking.

Example:

/**
 * @api {get} /users/:id Get User
 * @apiName GetUser
 */

@apiGroup

@apiGroup group

Groups related API endpoints together in the documentation.

Example:

/**
 * @api {get} /users/:id Get User
 * @apiName GetUser
 * @apiGroup User
 */

@apiVersion

@apiVersion version

Specifies the API version, enables version comparison features.

Example:

/**
 * @api {get} /users/:id Get User
 * @apiVersion 1.2.0
 * @apiName GetUser
 * @apiGroup User
 */

@apiDescription

@apiDescription text

Detailed description of the API endpoint functionality.

Example:

/**
 * @api {get} /users/:id Get User
 * @apiDescription Retrieves detailed information about a specific user
 * including profile data, permissions, and activity status.
 */

Parameter Tags

@apiParam

@apiParam [(group)] [{type}] [field=defaultValue] [description]

Documents URL path parameters.

Format Options:

(group): Optional parameter grouping
{type}: Data type (String, Number, Boolean, Object, Array, etc.)
field: Parameter name
=defaultValue: Default value
description: Parameter description

Examples:

/**
 * @apiParam {Number} id User unique ID
 * @apiParam {String} [region=us] User region (optional with default)
 * @apiParam (Authentication) {String} token Access token
 */

@apiQuery

@apiQuery [(group)] [{type}] [field=defaultValue] [description]

Documents query string parameters.

Examples:

/**
 * @apiQuery {Number} [limit=10] Maximum number of results
 * @apiQuery {Number} [offset=0] Result offset for pagination
 * @apiQuery {String} [sort=name] Sort field
 * @apiQuery {String="asc","desc"} [order=asc] Sort order
 */

@apiBody

@apiBody [(group)] [{type}] [field=defaultValue] [description]

Documents request body parameters for POST, PUT, PATCH requests.

Examples:

/**
 * @apiBody {String} name User full name
 * @apiBody {String} email User email address
 * @apiBody {Number} [age] User age (optional)
 * @apiBody {Boolean} [active=true] User active status
 * @apiBody {Object} profile User profile information
 * @apiBody {String} profile.bio User biography
 * @apiBody {String[]} profile.interests Array of user interests
 */

@apiHeader

@apiHeader [(group)] [{type}] [field=defaultValue] [description]

Documents required HTTP headers.

Examples:

/**
 * @apiHeader {String} Authorization Bearer token for authentication
 * @apiHeader {String} Content-Type=application/json Request content type
 * @apiHeader (Optional) {String} X-Request-ID Optional request tracking ID
 */

Response Tags

@apiSuccess

@apiSuccess [(group)] [{type}] field [description]

Documents successful response fields.

Examples:

/**
 * @apiSuccess {Number} id User unique ID
 * @apiSuccess {String} name User full name
 * @apiSuccess {String} email User email address
 * @apiSuccess {Object} profile User profile data
 * @apiSuccess {String} profile.bio User biography
 * @apiSuccess {String[]} profile.interests User interests array
 * @apiSuccess (Metadata) {Date} createdAt Account creation date
 * @apiSuccess (Metadata) {Date} updatedAt Last update date
 */

@apiError

@apiError [(group)] [{type}] field [description]

Documents error response fields and conditions.

Examples:

/**
 * @apiError UserNotFound The requested user was not found
 * @apiError (Authentication) Unauthorized Invalid or missing authentication
 * @apiError (Validation) ValidationError Request data validation failed
 * @apiError (500 Internal Server Error) InternalError Server error occurred
 */

Example Tags

@apiExample

@apiExample {type} title
content

Provides code examples for API usage.

Examples:

/**
 * @apiExample {curl} Curl Example
 * curl -X GET "https://api.example.com/users/123" \
 *      -H "Authorization: Bearer your-token"
 *
 * @apiExample {javascript} JavaScript Example
 * const response = await fetch('/users/123', {
 *   headers: {
 *     'Authorization': 'Bearer your-token'
 *   }
 * });
 * const user = await response.json();
 *
 * @apiExample {python} Python Example
 * import requests
 * 
 * response = requests.get(
 *     'https://api.example.com/users/123',
 *     headers={'Authorization': 'Bearer your-token'}
 * )
 * user = response.json()
 */

@apiParamExample

@apiParamExample {type} title
content

Provides examples of parameter usage.

Example:

/**
 * @apiParamExample {json} Request Body Example
 * {
 *   "name": "John Doe",
 *   "email": "john@example.com",
 *   "profile": {
 *     "bio": "Software developer",
 *     "interests": ["coding", "music"]
 *   }
 * }
 */

@apiHeaderExample

@apiHeaderExample {type} title
content

Provides examples of header usage.

Example:

/**
 * @apiHeaderExample {json} Header Example
 * {
 *   "Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGc...",
 *   "Content-Type": "application/json",
 *   "X-Request-ID": "req-12345"
 * }
 */

@apiSuccessExample

@apiSuccessExample {type} title
content

Provides examples of successful responses.

Example:

/**
 * @apiSuccessExample {json} Success Response
 * HTTP/1.1 200 OK
 * {
 *   "id": 123,
 *   "name": "John Doe",
 *   "email": "john@example.com",
 *   "profile": {
 *     "bio": "Software developer",
 *     "interests": ["coding", "music"]
 *   },
 *   "createdAt": "2023-01-15T10:30:00Z",
 *   "updatedAt": "2023-01-16T14:20:00Z"
 * }
 */

@apiErrorExample

@apiErrorExample {type} title
content

Provides examples of error responses.

Example:

/**
 * @apiErrorExample {json} Error Response
 * HTTP/1.1 404 Not Found
 * {
 *   "error": "UserNotFound",
 *   "message": "User with ID 123 was not found",
 *   "code": 404
 * }
 *
 * @apiErrorExample {json} Validation Error
 * HTTP/1.1 400 Bad Request
 * {
 *   "error": "ValidationError",
 *   "message": "Request validation failed",
 *   "details": [
 *     {
 *       "field": "email",
 *       "message": "Invalid email format"
 *     }
 *   ]
 * }
 */

Control Tags

@apiPermission

@apiPermission name

Documents required permissions or access levels.

Example:

/**
 * @api {delete} /users/:id Delete User
 * @apiPermission admin
 * @apiPermission user:delete
 */

@apiPrivate

@apiPrivate

Marks an API as private (excluded from documentation unless --private flag is used).

Example:

/**
 * @api {get} /internal/stats Get Internal Stats
 * @apiPrivate
 * @apiDescription Internal API for system monitoring
 */

@apiDeprecated

@apiDeprecated [text]

Marks an API as deprecated with optional migration information.

Examples:

/**
 * @api {get} /users/:id Get User (Old)
 * @apiDeprecated
 *
 * @api {get} /v2/users/:id Get User (New)
 * @apiDeprecated Use /v2/users/:id instead. This endpoint will be removed in v3.0.
 */

@apiSampleRequest

@apiSampleRequest url
@apiSampleRequest off

Specifies a custom URL for sample requests or disables sample requests.

Examples:

/**
 * @api {get} /users/:id Get User
 * @apiSampleRequest https://api.example.com
 *
 * @api {post} /admin/reset Reset System
 * @apiSampleRequest off
 */

Template Tags

@apiDefine

@apiDefine name [title]
description

Defines a reusable template block.

Example:

/**
 * @apiDefine UserResponse
 * @apiSuccess {Number} id User unique ID
 * @apiSuccess {String} name User full name
 * @apiSuccess {String} email User email address
 * @apiSuccess {Date} createdAt Account creation date
 */

/**
 * @apiDefine AuthenticationError
 * @apiError (Authentication) Unauthorized Invalid authentication token
 * @apiError (Authentication) Forbidden Insufficient permissions
 * @apiErrorExample {json} Authentication Error
 * HTTP/1.1 401 Unauthorized
 * {
 *   "error": "Unauthorized",
 *   "message": "Invalid or expired token"
 * }
 */

@apiUse

@apiUse name

Includes a previously defined template block.

Example:

/**
 * @api {get} /users/:id Get User
 * @apiName GetUser
 * @apiGroup User
 * @apiUse UserResponse
 * @apiUse AuthenticationError
 */

/**
 * @api {put} /users/:id Update User
 * @apiName UpdateUser
 * @apiGroup User
 * @apiUse UserResponse
 * @apiUse AuthenticationError
 */

Advanced Type Definitions

Complex Types

/**
 * @apiBody {String="small","medium","large"} size Size option
 * @apiBody {Number{1-100}} priority Priority level (1-100)
 * @apiBody {String{6..128}} password Password (6-128 characters)
 * @apiBody {Object[]} items Array of item objects
 * @apiBody {String} items.name Item name
 * @apiBody {Number} items.quantity Item quantity
 */

Optional and Required Fields

/**
 * @apiBody {String} name Required field
 * @apiBody {String} [email] Optional field
 * @apiBody {String} [region=us] Optional with default value
 * @apiBody {Boolean} [active=true] Optional boolean with default
 */

Nested Objects

/**
 * @apiBody {Object} user User information
 * @apiBody {String} user.name User full name
 * @apiBody {String} user.email User email
 * @apiBody {Object} user.profile User profile
 * @apiBody {String} user.profile.bio User biography
 * @apiBody {String[]} user.profile.interests User interests
 * @apiBody {Object} user.settings User settings
 * @apiBody {Boolean} user.settings.notifications Enable notifications
 * @apiBody {String} user.settings.theme=light UI theme preference
 */

Complete Example

/**
 * @apiDefine UserObject
 * @apiSuccess {Number} id User unique ID
 * @apiSuccess {String} name User full name
 * @apiSuccess {String} email User email address
 * @apiSuccess {Object} profile User profile information
 * @apiSuccess {String} profile.bio User biography
 * @apiSuccess {String[]} profile.interests User interests
 * @apiSuccess {Date} createdAt Account creation timestamp
 * @apiSuccess {Date} updatedAt Last update timestamp
 */

/**
 * @apiDefine AuthenticationRequired
 * @apiHeader {String} Authorization Bearer token for authentication
 * @apiError (Authentication) Unauthorized Invalid or missing authentication token
 * @apiError (Authentication) Forbidden Insufficient permissions for this operation
 */

/**
 * @api {get} /users/:id Get User Information
 * @apiVersion 1.2.0
 * @apiName GetUser
 * @apiGroup User
 * @apiDescription Retrieves detailed information about a specific user including
 * profile data, interests, and account metadata. Requires valid authentication token.
 *
 * @apiParam {Number} id User unique identifier
 * @apiQuery {String[]} [fields] Specific fields to include in response
 * @apiQuery {Boolean} [include_profile=true] Include profile information
 *
 * @apiUse AuthenticationRequired
 * @apiUse UserObject
 *
 * @apiExample {curl} cURL Example
 * curl -X GET "https://api.example.com/users/123?fields=name,email&include_profile=true" \
 *      -H "Authorization: Bearer your-access-token"
 *
 * @apiExample {javascript} JavaScript Example
 * const response = await fetch('/users/123', {
 *   headers: {
 *     'Authorization': 'Bearer your-access-token'
 *   }
 * });
 * const user = await response.json();
 *
 * @apiSuccessExample {json} Success Response
 * HTTP/1.1 200 OK
 * {
 *   "id": 123,
 *   "name": "John Doe",
 *   "email": "john@example.com",
 *   "profile": {
 *     "bio": "Software developer and tech enthusiast",
 *     "interests": ["programming", "music", "travel"]
 *   },
 *   "createdAt": "2023-01-15T10:30:00Z",
 *   "updatedAt": "2023-01-16T14:20:00Z"
 * }
 *
 * @apiError UserNotFound The requested user ID does not exist
 * @apiErrorExample {json} User Not Found
 * HTTP/1.1 404 Not Found
 * {
 *   "error": "UserNotFound",
 *   "message": "User with ID 123 was not found"
 * }
 */
function getUser(id) {
  // Implementation
}

Install with Tessl CLI