Referencia OpenAPI

Esta página es la referencia técnica vigente para integraciones con la API REST de CECOM BRYSA en producción.

Estado en Producción

La documentación pública de producción se consulta en este sitio Docusaurus. El endpoint https://api.cecom-brysa.cl/api-docs no se mantiene como entrada pública: si Swagger UI no está habilitado por variable de entorno, el backend redirige a esta referencia.

Entorno	Referencia
Producción	https://www.cecom-brysa.cl/docs/api/referencia
Desarrollo local	http://localhost:3001/api-docs

Uso Recomendado

• Use esta página para validar contratos técnicos antes de integrar.
• Use Swagger UI en local o en un entorno interno controlado.
• No publique tokens JWT ni credenciales en capturas, tickets o documentación.
• Si necesita exportar la especificación completa, genérela desde el backend del entorno autorizado.

Swagger UI

Swagger UI sigue disponible para desarrollo local en /api-docs. En producción solo debe habilitarse de forma intencional con ENABLE_SWAGGER_IN_PRODUCTION=true y controles de acceso adecuados.

Generar Especificación

JSON desde un entorno autorizado

curl http://localhost:3001/api-docs.json -o openapi.json

YAML desde un entorno autorizado

curl http://localhost:3001/api-docs.yaml -o openapi.yaml

Usar Swagger UI

Autenticarse

1. Abrir Swagger UI en /api-docs dentro del entorno autorizado
2. Clic en botón "Authorize" (candado verde)
3. En el campo de valor, ingresar solo el token (sin "Bearer"):

   eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

4. Clic en "Authorize"
5. Cerrar el modal

Ahora todas las requests incluirán el token automáticamente.

Probar un Endpoint

1. Expandir el endpoint deseado
2. Clic en "Try it out"
3. Completar parámetros requeridos
4. Clic en "Execute"
5. Ver respuesta en la sección "Responses"

Generar Especificación desde Backend

Si necesita regenerar o actualizar la especificación OpenAPI:

Desde el Código

La especificación se genera automáticamente a partir de:

• Comentarios JSDoc en los archivos de rutas
• Esquemas definidos en swagger.ts

Ubicación de los Comentarios

Los comentarios JSDoc deben estar en los archivos de rutas:

backend/src/modules/*/routes/*.routes.ts

Ejemplo de Anotación

/**
 * @swagger
 * /api/brigadista:
 *   get:
 *     tags: [Brigadistas]
 *     summary: Listar brigadistas
 *     description: Retorna lista paginada de brigadistas
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - name: page
 *         in: query
 *         schema:
 *           type: integer
 *           default: 1
 *       - name: limit
 *         in: query
 *         schema:
 *           type: integer
 *           default: 20
 *     responses:
 *       200:
 *         description: Lista de brigadistas
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/PaginatedResponse'
 *       401:
 *         description: No autenticado
 */
router.get('/', protect, brigadistaController.list);

Esquemas Comunes

Error

Error:
  type: object
  properties:
    success:
      type: boolean
      example: false
    message:
      type: string
    errors:
      type: array
      items:
        type: object
        properties:
          field:
            type: string
          message:
            type: string

SuccessResponse

SuccessResponse:
  type: object
  properties:
    success:
      type: boolean
      example: true
    message:
      type: string
    data:
      type: object

PaginatedResponse

PaginatedResponse:
  type: object
  properties:
    success:
      type: boolean
    data:
      type: array
    pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        totalPages:
          type: integer

Tags (Grupos)

Los endpoints están organizados por tags:

Tag	Descripción
Auth	Autenticación y sesiones
Users	Gestión de usuarios
Brigadistas	Personal y asistencia
Emergencies	Bitácora de emergencias
Resources	Vehículos y equipos
Manual Dotation	Dotación manual de carros por turno
Fuel	Registro de combustible
Inventory	Control de inventario
Shift Handover	Entrega de turno
Communication Tests	Pruebas de comunicación
Locations	Puntos georreferenciados
Dispatch Alerts	Alertas de despacho
Master Data	Datos maestros
Tenants	Gestión multi-tenant

---

Para desarrolladores backend

Si necesita agregar documentación para nuevos endpoints, mantenga los comentarios JSDoc en los archivos backend/src/modules/*/routes/*.routes.ts y verifique la configuración en backend/src/config/swagger.ts.

Herramientas Recomendadas

• Postman: Importe el archivo openapi.json para generar una colección
• Insomnia: Soporte nativo para OpenAPI
• VSCode REST Client: Use archivos .http con la especificación