snap-api-docs 📝

Documentación de API instantánea para desarrolladores modernos. Genera especificaciones OpenAPI 3.1 escaneando comentarios JSDoc. Sin YAML, sin configuraciones complejas.

snap-api-docs es una CLI que analiza tus archivos .js o .ts, procesa comentarios especiales y genera un archivo documentation.json con tu especificación OpenAPI lista para usar.

🚀 Instalación

npm install snap-api-docs --save-dev

⚡ Guía Rápida (3 pasos)

1. Agregá el script en tu package.json

"scripts": {
  "docs": "snap-api"
}

2. Comenta tus rutas usando JSDoc

/**
 * @endpoint GET /api/users
 * @group Usuarios
 * @desc Obtiene usuarios activos
 * @response 200 {object} - Lista de usuarios
 * @response 500 {object} - Error de servidor
 */
app.get('/api/users', (req, res) => { ... });

3. Ejecutá

npm run docs

El archivo documentation.json se genera automáticamente en:

• src/docs/documentation.json si existe carpeta src/
• ./docs/documentation.json si no existe

📚 Sintaxis Completa

@endpoint

Define método + ruta.

/**
 * @endpoint POST /api/login
 * @group Auth
 * @desc Inicia sesión y devuelve un token
 */

@param

Define parámetros de path, query o header.

/**
 * @endpoint GET /api/users/:id
 * @param id.path - ID del usuario (Requerido)
 * @param role.query - Rol (admin/user)
 * @param Authorization.header - Token Bearer
 */

@body

Define el cuerpo JSON que espera la ruta.

/**
 * @endpoint POST /api/products
 * @body {object} - {name, price}
 */

@response

Define respuestas del endpoint.

/**
 * @endpoint GET /api/products
 * @response 200 {array} - Lista de productos
 * @response 404 {object} - No encontrado
 */

💎 Modelos Reutilizables (Schemas)

1. Definí un Schema

/**
 * @schema User
 * @field {string} id - UUID
 * @field {string} name - Nombre
 * @field {string} email - Email
 */
export class User { ... }

2. Usalo en tus endpoints

/**
 * @endpoint GET /api/users
 * @response 200 {User[]} - Usuarios
 */

⚙️ Configuración CLI (Opcional)

| Flag | Alias | Descripción | Default | | --------------- | ----- | ----------------- | ------------------- | | --input | -i | Patrón a escanear | **/*.{js,ts} | | --output | -o | Ruta del JSON | Auto | | --title | -t | Título | API Documentation | | --api-version | -v | Versión OpenAPI | 3.1.0 |

Ejemplo:

"docs": "snap-api -i \"./routes/*.js\" -t \"Mi API\""

📥 Importar el JSON en Postman

1. Ejecutá npm run docs para generar documentation.json.

2. En Postman:

   • Abrí File → Import
   • Seleccioná el archivo documentation.json
   • Postman lo convertirá en una colección automáticamente (OpenAPI → Collection)

Listo.

📄 Licencia

MIT — https://opensource.org/licenses/MIT