El Sistema de Autenticación Dual de APIDoc 4.0 permite proteger la documentación de API mediante dos métodos de autenticación que pueden funcionar de forma independiente o complementaria:
Edita el archivo apidoc.json en tu proyecto y agrega la sección login:
{
"name": "Mi API Documentation",
"version": "1.0.0",
"description": "Documentación de mi API",
"login": {
"active": true,
"admited": [
{
"email": "admin@miempresa.com",
"password": "mi_password_seguro"
},
{
"email": "usuario@miempresa.com",
"password": "otro_password"
}
],
"urlAuth": "https://auth.miempresa.com/api/login",
"value_form": {
"email": "email",
"password": "password"
},
"response_success": 200,
"response_error": 401
}
}
Ejecuta APIDoc normalmente:
# Instalar APIDoc 4.0
npm install -g @hrefcl/apidoc
# Generar documentación con autenticación
apidoc -i src/ -o docs/
El sistema funciona con cualquier servidor web estático:
# Desarrollo
npx serve docs/ -p 8080
# Producción con Nginx
# Simplemente coloca los archivos en tu directorio web
Los usuarios se definen directamente en apidoc.json. Las contraseñas se hashean automáticamente durante la generación.
Configuración:
{
"login": {
"active": true,
"admited": [
{
"email": "usuario@ejemplo.com",
"password": "password123"
}
]
}
}
Ventajas:
Desventajas:
Integración con tu sistema de autenticación existente mediante API REST.
Configuración:
{
"login": {
"active": true,
"urlAuth": "https://api.miempresa.com/auth/login",
"value_form": {
"email": "username",
"password": "pass"
},
"response_success": 200,
"response_error": 401
}
}
Ventajas:
API Requerida:
Tu endpoint debe recibir POST con:
{
"username": "usuario@ejemplo.com",
"pass": "password123"
}
Y responder:
Puedes combinar ambos métodos. El sistema intentará primero la autenticación local, y luego la remota:
{
"login": {
"active": true,
"admited": [
{
"email": "admin@local.com",
"password": "admin123"
}
],
"urlAuth": "https://api.miempresa.com/auth/login",
"value_form": {
"email": "email",
"password": "password"
},
"response_success": 200,
"response_error": 401
}
}
El sistema protege automáticamente estas secciones:
sections)header)footer)project)Para APIs con nombres de campo diferentes:
{
"login": {
"value_form": {
"email": "user_email", // Campo email en tu API
"password": "user_password" // Campo password en tu API
}
}
}
{
"login": {
"response_success": 200, // Código de éxito
"response_error": 403 // Código de error
}
}
{
"login": {
"active": true,
"sessionTimeout": 3600, // Timeout en segundos (por defecto: 1 hora)
"encryptionStrength": 256, // AES-256 (no modificar)
"hashIterations": 10000 // Iteraciones PBKDF2 (no modificar)
}
}
{
"name": "API Interna - MiStartup",
"version": "2.1.0",
"login": {
"active": true,
"admited": [
{
"email": "ceo@mistartup.com",
"password": "super_secreto_2024"
},
{
"email": "dev@mistartup.com",
"password": "dev_password"
},
{
"email": "qa@mistartup.com",
"password": "testing123"
}
]
}
}
{
"name": "API Corporativa",
"version": "1.0.0",
"login": {
"active": true,
"urlAuth": "https://sso.miempresa.com/oauth/token",
"value_form": {
"email": "username",
"password": "password"
},
"response_success": 200,
"response_error": 401
}
}
{
"name": "API con Acceso Dual",
"version": "3.2.1",
"login": {
"active": true,
"admited": [
{
"email": "emergency@empresa.com",
"password": "emergency_access_2024"
}
],
"urlAuth": "https://auth.empresa.com/api/login",
"value_form": {
"email": "email",
"password": "password"
},
"response_success": 200,
"response_error": 400
}
}
mi-proyecto/
├── apidoc.json # Configuración principal
├── src/ # Tu código fuente con comentarios @api
├── docs/ # Documentación generada
│ ├── index.html # Página principal con autenticación
│ ├── assets/
│ │ ├── main.bundle.js # Bundle con AuthManager
│ │ └── main.bundle.css # Estilos con tema oscuro/claro
│ └── test-workflow.html # Página de pruebas
// Instancia global disponible en el navegador
window.authManager: AuthManager
// Métodos principales
authManager.isAuthenticated(): boolean
authManager.login(email: string, password: string): Promise<{success: boolean, message: string}>
authManager.logout(): void
authManager.getSessionInfo(): AuthSession | null
// Escuchar eventos de login
document.addEventListener('apidoc:login:success', (event) => {
console.log('Usuario autenticado:', event.detail);
});
document.addEventListener('apidoc:login:error', (event) => {
console.log('Error de login:', event.detail);
});
document.addEventListener('apidoc:logout', (event) => {
console.log('Usuario desconectado');
});
<script>
document.addEventListener('DOMContentLoaded', function() {
// Esperar a que el AuthManager esté disponible
if (window.authManager && window.authManager.isAuthenticated()) {
console.log('Usuario ya autenticado');
// Tu código personalizado aquí
}
});
</script>
Para Autenticación Local:
{
"admited": [
{
"email": "admin@empresa.com",
"password": "MinimoCambiarEstaContraseñaEnProduccion2024!"
}
]
}
Para Autenticación Remota:
Configuración de Servidor Web:
Nginx:
server {
listen 443 ssl;
server_name docs.miapi.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
root /var/www/apidoc;
index index.html;
try_files $uri $uri/ =404;
# Headers de seguridad
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
}
}
Apache (.htaccess):
# Seguridad básica
Header always set X-Frame-Options DENY
Header always set X-Content-Type-Options nosniff
Header always set X-XSS-Protection "1; mode=block"
# Forzar HTTPS
RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
Limitaciones de la Autenticación Local:
Recomendaciones:
Causa: Timing de inicialización
Solución:
// Verificar en consola del navegador
console.log('AuthManager available:', !!window.AuthManager);
console.log('Login config:', window.LOGIN_CONFIG);
Si AuthManager no está disponible:
npm run build:exampleCausa: Problema de hash o configuración
Solución:
# Usar el script de validación
cd tmp/apidoc-output
node test-credentials.js
Causa: DOM destruido prematuramente
Verificación:
// En consola del navegador
document.getElementById('template-header') // Debe existir
document.getElementById('sidenav') // Debe existir
Solución: El sistema ya incluye la corrección automática
Debugging:
// Verificar configuración
console.log('Remote config:', {
url: window.LOGIN_CONFIG?.urlAuth,
fields: window.LOGIN_CONFIG?.value_form
});
Verificar tu API:
# Probar manualmente
curl -X POST https://tu-api.com/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"test@test.com","password":"test123"}'
Scripts incluidos:
# Validación completa del sistema
node validate-system.js
# Verificar credenciales
node test-credentials.js
# Guía completa de testing
node final-test-guide.js
Debug en navegador:
// Estado de autenticación
window.authManager?.getSessionInfo()
// Configuración cargada
window.LOGIN_CONFIG
// Verificar templates
Object.keys(Handlebars.templates || {})
graph TD
A[apidoc.json] --> B[AuthProcessor]
B --> C[Encrypted HTML]
C --> D[Browser]
D --> E[AuthManager]
E --> F{Auth Type}
F -->|Local| G[Hash Validation]
F -->|Remote| H[API Request]
G --> I[Session Creation]
H --> I
I --> J[Content Decryption]
J --> K[UI Display]
Inicialización:
Proceso de Login:
Post-Autenticación:
interface LoginConfig {
active: boolean; // Activar/desactivar autenticación
admited?: Array<{ // Usuarios locales
email: string;
password: string;
}>;
urlAuth?: string; // URL de autenticación remota
value_form?: { // Mapeo de campos
email: string;
password: string;
};
response_success?: number; // Código HTTP de éxito
response_error?: number; // Código HTTP de error
}
interface AuthSession {
email: string; // Email del usuario
authenticated: boolean; // Estado de autenticación
expires: number; // Timestamp de expiración
method: 'local' | 'remote'; // Método usado
}
| Archivo | Propósito | Ubicación |
|---|---|---|
lib/core/auth-processor.ts |
Procesador principal de autenticación | Backend/Build |
template/src/components/auth.ts |
Manager de autenticación cliente | Frontend/Bundle |
template/src/components/content-protection.ts |
Sistema de protección | Frontend/Bundle |
template/src/main.ts |
Integración principal | Frontend/Bundle |
template/index.html |
Template con configuración | Template |
lib/writer.ts |
Integración con proceso de build | Backend/Build |
# Desarrollo completo
npm run dev:template # Compilar y servir con recarga
# Testing
npm run build:example # Generar documentación de ejemplo
npm run test # Ejecutar tests
npm run typecheck # Verificación TypeScript
# Producción
npm run build:clean # Build limpio para producción
npm run prepublishOnly # Preparar para publicación
CSS Custom Properties:
:root {
--auth-overlay-bg: rgba(0, 0, 0, 0.8);
--auth-form-bg: white;
--auth-input-border: #d1d5db;
--auth-button-bg: #3b82f6;
}
[data-theme="dark"] {
--auth-form-bg: #1f2937;
--auth-input-border: #374151;
}
JavaScript Hooks:
// Personalizar el proceso de login
window.addEventListener('apidoc:auth:init', (event) => {
// Tu código personalizado de inicialización
});
window.addEventListener('apidoc:auth:success', (event) => {
// Tu código post-autenticación
console.log('Usuario:', event.detail.user);
});
Disponibles en el repositorio:
example/apidoc.json - Configuración completatmp/apidoc-output/ - Documentación generadatest-*.js - Scripts de testingPara contribuir al desarrollo del sistema de autenticación:
git checkout -b feature/auth-mejoragit commit -m 'Add: nueva funcionalidad'git push origin feature/auth-mejoraMIT License - Ver archivo LICENSE para detalles completos.
El Sistema de Autenticación Dual de APIDoc 4.0 proporciona una solución robusta y flexible para proteger documentación de API. Con soporte para autenticación local y remota, encriptación de contenido y una interfaz moderna, es ideal tanto para equipos pequeños como para grandes organizaciones.
¡Tu documentación API ahora está protegida y lista para producción! 🚀
Documentación actualizada para APIDoc 4.0 - Última actualización: $(date)