APIDoc 5.0

RESTful web API & MQTT Protocol Documentation Generator - Generador moderno de documentación para APIs REST y protocolos MQTT con soporte completo para TypeScript, autenticación dual y contenido personalizado.

🚀 ¿Qué es APIDoc?

APIDoc genera documentación completa para APIs RESTful y protocolos MQTT desde comentarios en el código fuente. Compatible con C#, Go, Dart, Java, JavaScript, PHP, TypeScript, Python, Ruby y más.

Ejemplo Rápido:

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

🎯 Inicio Rápido

# Instalación global
npm install -g @hrefcl/apidoc

# Generar documentación
apidoc -i src/ -o docs/

# Ver documentación
open docs/index.html

📚 Documentación Completa

🛠️ Configuración y Personalización

• 📋 Configuración - Configuración completa de apidoc.json
• 🎨 Iconos y Personalización - Font Awesome, logos, temas
• 📄 Markdown Personalizado - Contenido personalizado para secciones
• 📄 Ejemplos de Markdown - Ejemplos prácticos

📋 Funcionalidad Core

• 📖 Parámetros APIDoc - Referencia completa de @api, @apiParam
• 💡 Ejemplos y Plantillas - Ejemplos de uso práctico
• 🔄 Versionado y Herencia - Gestión de versiones y reutilización
• ⚙️ Uso Programático - Integración con Node.js

🌐 Protocolos y Formatos Modernos

• 🔌 OpenAPI 3.0 - Soporte nativo y exportación
• 📡 Protocolo MQTT - Documentación completa para IoT
• 📊 Schemas TypeScript - Integración con @apiSchema

🔐 Seguridad y Autenticación

• 🛡️ Sistema de Autenticación - Protección de documentación
• 🚀 Configuración Rápida Auth - Setup en 3 pasos
• 👨‍💻 Referencia Desarrollador - API técnica de autenticación

🛠️ Desarrollo y Deploy

• 🔨 Desarrollo Local - Configuración de entorno de desarrollo
• 🐳 Docker y Contenedores - Uso y despliegue con contenedores
• 🔧 Herramientas de Build - Integración con Grunt, Webpack, etc.

🌟 Características Principales v5.0.0

📝 Contenido Markdown Personalizado

Agrega contenido markdown personalizado a cualquier grupo de API con formato enriquecido:

{
  "settings": {
    "Users": {
      "icon": "fa-user",
      "title": "Gestión de Usuarios",
      "filename": "users.md"
    }
  }
}

📡 Soporte Completo para MQTT

Documenta protocolos MQTT con parsers especializados:

/**
 * @apiMqtt {publish} v1/sensors/{id}/data Publish Sensor Data
 * @apiGroup IoT
 * @apiMqttQos 1
 * @apiMqttRetain false
 * @apiMqttPayload {Object} data Sensor data payload
 */

Características MQTT:

• ✅ 16+ parsers MQTT implementados (@apiMqtt, @apiMqttPayload, @apiMqttQos, etc.)
• ✅ Template específico para documentación MQTT
• ✅ CSS styling para métodos publish/subscribe
• ✅ Configuración de broker MQTT en apidoc.json para template
• ✅ CLI options: --mqtt-only, --fail-on-mqtt-schema-error

🔐 Sistema de Autenticación Dual

Protege tu documentación con autenticación local y remota:

Modo Local (Sin servidor):

{
  "login": {
    "active": true,
    "encryptionKey": "tu-clave-base64",
    "admited": [
      {
        "email": "[email protected]",
        "password": "secure123",
        "name": "Admin User"
      }
    ]
  }
}

Modo Servidor:

{
  "login": {
    "active": true,
    "encryptionKeyFromServer": true,
    "urlAuth": "https://api.company.com/auth/login",
    "value_form": {
      "email": "email",
      "password": "password"
    },
    "response_success": 200,
    "response_error": 401
  }
}

Características de Seguridad:

• ✅ Encriptación AES-256-GCM
• ✅ Ofuscación de claves de encriptación
• ✅ JWT con expiración de 24 horas
• ✅ Lista de usuarios encriptada
• ✅ No almacena claves en sessionStorage

🌐 OpenAPI 3.0 Nativo

Escribe especificaciones OpenAPI directamente en comentarios:

/**
 * @openapi
 * /api/users/{id}:
 *   get:
 *     summary: Get user by ID
 *     parameters:
 *       - name: id
 *         in: path
 *         required: true
 *         schema:
 *           type: integer
 */

📊 Integración con TypeScript

Genera documentación desde interfaces TypeScript:

/**
 * @api {get} /users/:id Get User
 * @apiSuccess {Object} user User data
 * @apiSchema {User} user
 * @apiSchemaFile ../types/user.ts
 */

🎨 Personalización Completa

• 160+ temas de resaltado de sintaxis
• Font Awesome 6.0+ para iconos
• Logos personalizados (light/dark mode)
• Orden personalizado de grupos
• Markdown enriquecido en secciones

🌍 Idiomas

• 🇪🇸 Español (Principal): Documentación

🔗 Enlaces y Recursos

• 📦 Paquete NPM
• 🏠 Sitio Web Oficial
• 💻 Repositorio GitHub

🤝 Soporte y Contribuciones

• 🐛 Reportar Issues
• 💬 Discusiones
• 📖 Guía de Contribución

📄 Licencia

MIT License - ver archivo LICENSE para detalles.