Snap API Docs ⚡

Documentación de API en un chasquido. Genera especificaciones OpenAPI 3.0 (Swagger) escaneando comentarios JSDoc. Soporta sintaxis simple y YAML avanzado. Es agnóstico al framework.

Snap API Docs es una suite pensada para desarrolladores que no quieren perder tiempo escribiendo YAML gigantes.

• 📦 @snap-api-docs/cli → Genera el JSON escaneando tus comentarios.
• 🎨 @snap-api-docs/ui → Interfaz visual para mostrar la documentación (Swagger UI limpio).

🚀 Instalación

Instalá cada herramienta según tu uso:

# 1. Generador (solo desarrollo)
npm install @snap-api-docs/cli --save-dev

# 2. Interfaz visual (para servir la documentación)
npm install @snap-api-docs/ui

⚡ Guía Rápida

1. Agregá el script

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

2. Comenta tu código

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

3. Generá la documentación

npm run docs

Esto crea una carpeta docs/ o src/docs/ con documentation.json.

📚 Sintaxis de Comentarios

Snap API Docs soporta dos modos: Simple (JSDoc) y Avanzado (YAML).

⭐ Modo Simple (Recomendado)

Definir un endpoint

/**
 * @endpoint POST /api/login
 * @group Auth
 * @desc Inicia sesión y retorna token
 * @body {object} - Credenciales {email, password}
 * @response 200 {object} - Login exitoso
 */

Parámetros

/**
 * @endpoint GET /api/users/:id
 * @param {string} id.path - El UUID del usuario
 * @param {string} role.query - Filtrar por rol
 */

Usando Schemas Reutilizables

1. Definir el Schema

/**
 * @schema User
 * @field {string} id - UUID único
 * @field {string} email - Correo del usuario
 */
export class User { ... }

2. Usarlo

/**
 * @endpoint GET /api/users
 * @response 200 {User[]} - Retorna un array de usuarios
 */

🧩 Modo Avanzado (YAML)

/**
 * @openapi
 * /api/complejo:
 *   post:
 *     summary: Ruta compleja
 *     responses:
 *       200:
 *         description: OK
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/User'
 */

🎨 Integración de la UI

@snap-api-docs/ui devuelve un HTML listo para servir con cualquier framework.

Con Express

import { getHtml } from '@snap-api-docs/ui';
import express from 'express';

const app = express();

app.use('/docs/json', express.static('docs/documentation.json'));

app.get('/docs', (req, res) => {
  res.send(getHtml('/docs/json', { title: 'Mi API Documentation' }));
});

app.listen(3000);

Con Fastify

import { getHtml } from '@snap-api-docs/ui';

fastify.get('/docs', (req, reply) => {
  const html = getHtml('/docs.json', { title: 'Fastify Docs' });
  reply.type('text/html').send(html);
});

⚙️ Configuración CLI

| Flag | Alias | Descripción | Default | | -------- | ----- | ------------------ | ---------------------- | | --input | -i | Patrón de archivos | **/*.{js,ts} | | --output | -o | Archivo de salida | Automático (src/docs/) | | --title | -t | Título de la API | API Docs | | --debug | — | Logs detallados | false |

📄 Licencia

Este proyecto está bajo licencia MIT.