📚 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.

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

npm install route-api-docs

🛠 Uso Básico

En tu archivo principal de Express (por ejemplo index.js o app.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) | | | Dark (Soft Night) | | | Pastel (Fun & Bright) | | | Ocean (Blue Fresh) | |

📝 Guía de Sintaxis JSDoc

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

1. Definir un Endpoint

/**
 * @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.

/**
 * @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.