Skip to content

Latest commit

 

History

History
243 lines (177 loc) · 6.76 KB

SWAGGER.md

File metadata and controls

243 lines (177 loc) · 6.76 KB

📚 Documentación Swagger/OpenAPI

🎯 Acceso a la Documentación Interactiva

Una vez que el servidor esté en ejecución, accede a la documentación interactiva de Swagger:

URL: http://localhost:4300/api-docs

📋 Características de Swagger UI

✅ Interfaz Interactiva

  • Exploración visual de todos los endpoints disponibles
  • Esquemas de datos con ejemplos en tiempo real
  • Probar peticiones directamente desde el navegador
  • Respuestas en vivo con códigos de estado HTTP

🔐 Autenticación en Swagger

Para probar endpoints protegidos:

  1. Click en el botón "Authorize" (candado verde en la parte superior)
  2. Ingresa tu API Key o Bearer Token:
    • API Key: Ingresa en el campo X-API-Key
    • Bearer Token: Ingresa en el campo BearerAuth
  3. Click en "Authorize" y luego "Close"
  4. Ahora puedes ejecutar peticiones autenticadas

Ejemplo de Autenticación

API Key:

dev-key-123

Bearer Token:

dev-token-123

📖 Secciones de la Documentación

1. Short Links

Endpoints para gestión CRUD de enlaces cortos (requieren autenticación):

  • GET /v1/short-links - Listar y filtrar enlaces
  • POST /v1/short-links - Crear nuevo enlace
  • GET /v1/short-links/{id} - Obtener enlace por ID
  • PATCH /v1/short-links/{id} - Actualizar enlace

2. Redirección

Endpoints públicos de redirección (sin autenticación):

  • GET /r/{codigo} - Redirección pública

3. Health

Endpoints de estado del servicio:

  • GET / - Landing page
  • GET /health - Health check

🧪 Probar Endpoints desde Swagger

Ejemplo: Crear un Enlace Corto

  1. Ve a la sección "Short Links"
  2. Expande POST /v1/short-links
  3. Click en "Try it out"
  4. Edita el cuerpo de la petición:
{
  "proyecto": "Marketing",
  "creado_por": "admin",
  "url_destino": "https://example.com/promo",
  "etiquetas": ["black-friday", "descuentos"]
}
  1. Click en "Execute"
  2. Observa la respuesta con el código HTTP 201 y el enlace creado

Ejemplo: Listar Enlaces con Filtros

  1. Ve a GET /v1/short-links
  2. Click en "Try it out"
  3. Completa los parámetros de query:
    • proyecto: Marketing
    • estado: ACTIVO
  4. Click en "Execute"
  5. Revisa el array de enlaces retornados

Ejemplo: Redirección Pública

  1. Primero crea un enlace y copia su codigo de la respuesta
  2. Ve a GET /r/{codigo}
  3. Click en "Try it out"
  4. Ingresa el código en el campo codigo
  5. Click en "Execute"
  6. Observarás una redirección HTTP 302 a la URL destino

📥 Exportar Especificación OpenAPI

Puedes obtener la especificación OpenAPI 3.0 en formato JSON:

URL: http://localhost:4300/api-docs.json

Uso de la Especificación

# Descargar especificación
curl http://localhost:4300/api-docs.json > openapi.json

# Importar en Postman
# File → Import → Upload Files → openapi.json

# Usar con generadores de código
npx @openapitools/openapi-generator-cli generate -i openapi.json -g typescript-axios -o ./client

🎨 Personalización de Swagger UI

La interfaz de Swagger está personalizada con:

  • Título personalizado: API Short Link - SimpleData Corp
  • Barra superior oculta: Para una interfaz más limpia
  • Favicon corporativo: Logo de SimpleData Corp

🔧 Configuración de Swagger

La configuración se encuentra en:

Archivo: src/config/swagger.ts

Estructura de la Configuración

{
  openapi: '3.0.0',
  info: {
    title: 'API Acortador de Enlaces - SimpleData Corp',
    version: '1.0.0',
    description: 'Descripción detallada...',
    contact: { ... },
    license: { ... }
  },
  servers: [
    { url: 'http://localhost:4300/v1', description: 'Desarrollo' },
    { url: 'https://lnk.simpledatacorp.com/v1', description: 'Producción' }
  ],
  components: {
    securitySchemes: { ... },
    schemas: { ... },
    responses: { ... }
  },
  tags: [ ... ]
}

📝 Anotaciones en el Código

Las anotaciones Swagger se encuentran directamente en los archivos de rutas:

  • src/routes/shortlink.route.ts - Endpoints de gestión
  • src/routes/redirect.route.ts - Endpoints de redirección
  • src/routes/index.route.ts - Endpoints de health

Ejemplo de Anotación

/**
 * @swagger
 * /v1/short-links:
 *   post:
 *     summary: Crear un nuevo enlace corto
 *     tags:
 *       - Short Links
 *     security:
 *       - ApiKeyAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/CreateShortLinkDTO'
 */
router.post('/', createShortLink);

🌐 Acceso en Producción

En producción, Swagger estará disponible en:

URL: https://lnk.simpledatacorp.com/api-docs

Seguridad en Producción

⚠️ Recomendaciones:

  1. Proteger Swagger con autenticación: Agregar middleware de autenticación
  2. Deshabilitar en producción: Configurar NODE_ENV para ocultar Swagger
  3. CORS restrictivo: Configurar orígenes permitidos

🔍 Solución de Problemas

Swagger UI no carga

  1. Verifica que el servidor esté corriendo: npm run dev
  2. Accede directamente al JSON: http://localhost:4300/api-docs.json
  3. Revisa los logs del servidor en la terminal

Errores de autenticación

  1. Verifica que tu API Key esté en el archivo .env
  2. Usa el botón "Authorize" antes de ejecutar peticiones
  3. Revisa que el header X-API-Key o Authorization se incluya

Esquemas no se muestran

  1. Verifica que los archivos de rutas tengan anotaciones @swagger
  2. Recompila el proyecto: npm run build
  3. Reinicia el servidor: Ctrl+C y luego npm run dev

📚 Recursos Adicionales

🎯 Próximos Pasos

  1. Explora los endpoints desde Swagger UI
  2. Prueba con datos reales usando el botón "Try it out"
  3. Exporta la especificación para usar con otras herramientas
  4. Integra con Postman importando el JSON de OpenAPI
  5. Genera clientes SDK usando herramientas de generación de código

Autor: Dey Gordillo
Email: dey.gordillo@simpledatacorp.com
Organización: SimpleData Corp
Versión: 1.0.0