npm package: @snap-api-docs/generator
Description: Generador de documentación OpenAPI minimalista.
Author: Daniel Riverol
Latest version: 1.0.3


# 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**.


![Version](https://img.shields.io/badge/version-1.0.0-green.svg)
[![MIT License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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:

```bash
# 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

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

### 2. Comenta tu código

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

```bash
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

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

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

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

**2. Usarlo**

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

---

### 🧩 Modo Avanzado (YAML)

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

```js
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

```js
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**.
[![MIT License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)