Referencia completa de todos los parámetros disponibles en APIDoc para documentar tus APIs.
Define un endpoint de API. Obligatorio para que APIDoc procese el bloque de documentación.
/**
* @api {method} path title
*/
Ejemplo:
/**
* @api {get} /user/:id Get User Information
* @apiName GetUser
* @apiGroup User
*/
| Parámetro | Descripción | Ejemplo |
|---|---|---|
method |
Método HTTP (GET, POST, PUT, DELETE, etc.) | get, post, put |
path |
Ruta del endpoint | /user/:id, /api/users |
title |
Título descriptivo del endpoint | Get User Information |
Define un nombre único para el endpoint. Recomendado siempre.
/**
* @apiName GetUser
*/
Agrupa endpoints relacionados. Recomendado siempre.
/**
* @apiGroup User
*/
Especifica la versión del endpoint.
/**
* @apiVersion 1.0.0
*/
Documenta parámetros de la URL.
/**
* @apiParam [(group)] [{type}] [field=defaultValue] [description]
*/
Ejemplos:
/**
* @apiParam {Number} id User's unique ID.
* @apiParam {String} [name] Optional user name.
* @apiParam {String} country="ES" Country code with default.
* @apiParam {Number} [age=18] Optional age with default.
* @apiParam (Login) {String} password Only for authenticated users.
*/
Documenta parámetros de query string.
/**
* @apiQuery {String} [search] Search term.
* @apiQuery {Number} [page=1] Page number.
* @apiQuery {String="asc","desc"} [sort="asc"] Sort direction.
*/
Documenta el cuerpo de la petición (para POST, PUT, etc.).
/**
* @apiBody {String} email User's email address.
* @apiBody {String} password User's password.
* @apiBody {String} [firstName] Optional first name.
* @apiBody {Object} [address] Optional address object.
* @apiBody {String} [address.street] Street address.
* @apiBody {String} [address.city] City name.
*/
Documenta headers requeridos.
/**
* @apiHeader {String} Authorization Bearer token.
* @apiHeader {String} Content-Type Must be application/json.
* @apiHeader (Optional) {String} X-API-Key Optional API key.
*/
Documenta respuestas exitosas.
/**
* @apiSuccess {String} firstname User's first name.
* @apiSuccess {String} lastname User's last name.
* @apiSuccess {Number} age User's age.
* @apiSuccess {Object} profile User profile information.
* @apiSuccess {String} profile.bio User biography.
*/
Documenta respuestas de error.
/**
* @apiError UserNotFound The user was not found.
* @apiError (Error 4xx) ValidationError Invalid input data.
* @apiError (Error 5xx) ServerError Internal server error.
*/
Muestra ejemplos de uso del endpoint.
/**
* @apiExample {curl} Example usage:
* curl -X GET https://api.example.com/user/123 \
* -H "Authorization: Bearer token123"
*/
Ejemplos de respuestas exitosas.
/**
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "id": 123,
* "name": "John Doe",
* "email": "john@example.com"
* }
*/
Ejemplos de respuestas de error.
/**
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound",
* "message": "User with ID 123 was not found"
* }
*/
Ejemplos de parámetros.
/**
* @apiParamExample {json} Request-Example:
* {
* "name": "John Doe",
* "email": "john@example.com",
* "age": 30
* }
*/
Ejemplos de headers.
/**
* @apiHeaderExample {json} Header-Example:
* {
* "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
* "Content-Type": "application/json"
* }
*/
Descripción detallada del endpoint.
/**
* @apiDescription This endpoint retrieves detailed user information
* including profile data, preferences, and account status.
*
* Requires authentication via Bearer token.
*/
Define permisos requeridos.
/**
* @apiPermission admin
* @apiPermission user
*/
Marca un endpoint como obsoleto.
/**
* @apiDeprecated use now (#User:GetUserProfile).
*/
Ignora un bloque de documentación.
/**
* @apiIgnore Not implemented yet
* @api {get} /user/:id
*/
Marca un endpoint como privado.
/**
* @apiPrivate
*/
Configura formularios de prueba.
/**
* @apiSampleRequest https://api.example.com
* @apiSampleRequest off // Deshabilita formulario
*/
Define bloques reutilizables.
/**
* @apiDefine UserNotFoundError
*
* @apiError UserNotFound The user was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
Incluye bloques definidos con @apiDefine.
/**
* @apiUse UserNotFoundError
*/
| Tipo | Descripción | Ejemplo |
|---|---|---|
String |
Cadena de texto | {String} name |
Number |
Número | {Number} age |
Boolean |
Verdadero/Falso | {Boolean} active |
Object |
Objeto | {Object} user |
Array |
Arreglo | {String[]} tags |
/**
* @apiParam {String{2..10}} username Username (2-10 chars).
* @apiParam {Number{1-100}} age Age between 1 and 100.
* @apiParam {String="admin","user"} role User role.
* @apiParam {String[]} tags Array of strings.
*/
/**
* @apiParam {Object} address User address.
* @apiParam {String} address.street Street name.
* @apiParam {String} address.city City name.
* @apiParam {String} address.country Country code.
* @apiParam {Object} address.coordinates GPS coordinates.
* @apiParam {Number} address.coordinates.lat Latitude.
* @apiParam {Number} address.coordinates.lng Longitude.
*/
/**
* @api {post} /user Create User
* @apiName CreateUser
* @apiGroup User
* @apiVersion 1.0.0
* @apiPermission admin
*
* @apiDescription Creates a new user account with the provided information.
* This endpoint requires admin privileges.
*
* @apiHeader {String} Authorization Bearer token.
* @apiHeader {String} Content-Type Must be application/json.
*
* @apiBody {String} email User's email address.
* @apiBody {String} password User's password (min 8 chars).
* @apiBody {String} firstName User's first name.
* @apiBody {String} lastName User's last name.
* @apiBody {String="admin","user","moderator"} [role="user"] User role.
* @apiBody {Object} [profile] Optional profile information.
* @apiBody {String} [profile.bio] User biography.
* @apiBody {String[]} [profile.interests] User interests.
*
* @apiSuccess {Number} id Unique user ID.
* @apiSuccess {String} email User's email address.
* @apiSuccess {String} firstName User's first name.
* @apiSuccess {String} lastName User's last name.
* @apiSuccess {String} role User's role.
* @apiSuccess {Date} createdAt Account creation date.
*
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 201 Created
* {
* "id": 123,
* "email": "john@example.com",
* "firstName": "John",
* "lastName": "Doe",
* "role": "user",
* "createdAt": "2023-01-15T10:30:00Z"
* }
*
* @apiError ValidationError Invalid input data.
* @apiError EmailExists Email already in use.
* @apiError Unauthorized Insufficient privileges.
*
* @apiErrorExample {json} Validation-Error:
* HTTP/1.1 400 Bad Request
* {
* "error": "ValidationError",
* "message": "Invalid email format",
* "field": "email"
* }
*
* @apiExample {curl} Example usage:
* curl -X POST https://api.example.com/user \
* -H "Authorization: Bearer your-token" \
* -H "Content-Type: application/json" \
* -d '{
* "email": "john@example.com",
* "password": "securepassword",
* "firstName": "John",
* "lastName": "Doe"
* }'
*/
Define operaciones MQTT.
/**
* @mqtt {publish} sensors/temperature Temperature Data
* @mqtt {subscribe} alerts/+/critical Critical Alerts
*/
Especifica el patrón del topic MQTT.
/**
* @topic sensors/{deviceId}/temperature
* @topic alerts/+/critical
*/
Documenta la estructura del payload.
/**
* @payload {Object} data Sensor data
* @payload {Number} data.temperature Temperature in Celsius
* @payload {Number} data.humidity Humidity percentage
*/
Define el nivel de Quality of Service.
/**
* @qos 0 // Fire and forget
* @qos 1 // At least once
* @qos 2 // Exactly once
*/