npm package: @route-api-docs/core
Description: > **Documentación de API automática, hermosa y ligera para Node.js y Express.**
Latest version: 1.0.3

# 📚 Route API Docs

> **Documentación de API automática, hermosa y ligera para Node.js y Express.**

Genera una página de documentación estática profesional escaneando tus comentarios JSDoc. Sin servidores pesados, sin configuraciones complejas, 100% Native Node.js.

<p align="center">
  <img src="./assets/banner.png" alt="Route API Docs Banner" width="800">
</p>


---

## ✨ Características

* **Zero Config:** Escanea tus rutas y genera el HTML automáticamente.
* **Native & Ligero:** Sin Webpack, sin Babel, sin dependencias pesadas. Archivos minificados.
* **4 Temas Integrados:** Default, Dark, Pastel y Ocean.
* **Interactividad:** Grupos y esquemas colapsables (Details/Summary nativo).
* **Syntax Highlighting:** Formateo de JSON estilo Monokai integrado.
* **Responsive:** Sidebar adaptable y menú móvil.
* **JSDoc Driven:** Documenta tu código donde vive, en los comentarios.

---

## 🚀 Instalación

Instala el paquete en tu proyecto:

```bash
npm install route-api-docs
```

---

## 🛠 Uso Básico

En tu archivo principal de Express (por ejemplo `index.js` o `app.js`):

```js
import express from 'express';
import path from 'node:path';
import { generateDocs } from 'route-api-docs';

const app = express();

// ... tus rutas y configuraciones ...

// Endpoint para servir la documentación
app.get('/docs', (req, res) => {
    // 1. Ruta donde están tus archivos de rutas (con comentarios JSDoc)
    const routesPath = path.join(process.cwd(), 'src/routes');
    
    // 2. Generar el HTML
    const html = generateDocs(routesPath, {
        title: 'Mi API Increíble',
        version: '1.0.0',
        theme: 'dark', // Opcional: default, dark, pastel, ocean
        baseUrl: 'http://localhost:3000' // Opcional: para mostrar URL completa
    });

    res.send(html);
});

app.listen(3000, () => console.log('Docs en http://localhost:3000/docs'));
```

---

## 🎨 Temas Disponibles

Puedes cambiar el aspecto visual pasando la opción `theme` en la configuración.

| Tema                      | Previsualización                                                                  |
| ------------------------- | --------------------------------------------------------------------------------- |
| **Default (Tech Light)**  | <img src="./assets/screenshots/theme_default.png" width="400" alt="Tema Default"> |
| **Dark (Soft Night)**     | <img src="./assets/screenshots/theme_dark.png" width="400" alt="Tema Dark">       |
| **Pastel (Fun & Bright)** | <img src="./assets/screenshots/theme_pastel.png" width="400" alt="Tema Pastel">   |
| **Ocean (Blue Fresh)**    | <img src="./assets/screenshots/theme_ocean.png" width="400" alt="Tema Ocean">     |

---

## 📝 Guía de Sintaxis JSDoc

Documenta tus archivos de rutas (`.js` o `.ts`) usando los siguientes tags.

### 1. Definir un Endpoint

```js
/**
 * @endpoint /api/users
 * @method GET
 * @group Usuarios
 * @desc Obtiene todos los usuarios activos.
 * @header {string} Authorization Token Bearer
 * @param {int} page Número de página
 * @return {Usuario} Array de usuarios
 * @status {200} Éxito
 * @example
 * [
 *   { "id": 1, "name": "Alice" }
 * ]
 */
router.get('/users', controller.getUsers);
```

---

### 2. Definir un Schema (Modelo de Datos)

Define tus modelos una vez y reutilízalos en `@return` o `@body`.

```js
/**
 * @schema Usuario
 * @desc Usuario registrado en el sistema.
 * @prop {integer} id ID único
 * @prop {string} name Nombre completo
 * @prop {string} email Email del usuario
 */
```

---

## 📌 Lista de Tags Soportados

| Tag         | Descripción                    | Ejemplo                           |
| ----------- | ------------------------------ | --------------------------------- |
| `@endpoint` | Ruta del endpoint              | `/api/v1/products`                |
| `@method`   | Método HTTP                    | `GET`, `POST`, `PUT`, `DELETE`    |
| `@group`    | Agrupa endpoints en el sidebar | `Productos`, `Auth`               |
| `@desc`     | Descripción corta              | Crea un nuevo producto            |
| `@header`   | Headers requeridos             | `{string} Authorization`          |
| `@param`    | Parámetros de URL/Query        | `{int} id ID del producto`        |
| `@body`     | Cuerpo de la petición (JSON)   | `{string} email`                  |
| `@return`   | Tipo de respuesta              | `{Producto} Objeto creado`        |
| `@status`   | Códigos HTTP posibles          | `{200} Ok`, `{404} No encontrado` |
| `@example`  | Ejemplo JSON de respuesta      | *(JSON válido debajo del tag)*    |
| `@schema`   | Define un modelo reutilizable  | `Usuario`                         |
| `@prop`     | Propiedad de un schema         | `{string} name`                   |

---

## 🤝 Contribuir

1. Haz un **Fork** del proyecto.
2. Crea una rama (`git checkout -b feature/nueva-funcionalidad`).
3. Haz Commit (`git commit -m 'Add some feature'`).
4. Push a la rama (`git push origin feature/nueva-funcionalidad`).
5. Abre un **Pull Request**.

---

Creado con ❤️ usando **Node.js nativo**.