Guía De Documentación

Esta guía define el contexto necesario para continuar documentando APIs de CETB manteniendo la misma estructura, criterios y nivel de detalle.

Fuente De Verdad

Para documentar un repositorio de API:

• Usar siempre la rama main como fuente técnica.
• Ignorar cambios locales sin commit.
• Ignorar ramas distintas a main, aunque contengan código más reciente.
• Ignorar archivos Docker cuando sólo sirvan para ambientes de desarrollo.
• No documentar secretos, credenciales, tokens ni URLs reales de conexión a base de datos o servicios internos.

Si main no contiene código suficiente para documentar, crear una página de estado indicando que no hay contrato técnico documentable en main.

Estructura Esperada

Cada API debe vivir en:

docs/apis/<nombre-api>/

Con estos archivos:

Archivo	Contenido
index.md	Resumen, stack, responsabilidades, rutas principales y criterios aplicados
configuracion.md	Runtime, variables de entorno sin valores sensibles, health check y scripts
arquitectura.md	Módulos, capas, providers, flujo principal y observaciones técnicas
modelo-datos.md	Entidades, campos, obligatoriedad, defaults, normalización y búsqueda
api-rest.md	Endpoints, parámetros, bodies, respuestas y errores esperados
despliegue-lambda.md	Entrada Lambda, bootstrap, handler y consideraciones serverless

La navegación debe agregarse en mkdocs.yml bajo APIs.

Campos Obligatorios

Toda documentación de modelo o API REST debe identificar explícitamente:

• Campos obligatorios.
• Campos opcionales.
• Campos condicionales.
• Campos de sistema.
• Defaults asignados por código o schema.
• Validaciones de DTO, como IsEmail, IsEnum, MaxLength, Min, Max, IsOptional.

Separar la obligatoriedad por operación cuando aplique:

• Creación.
• Actualización.
• Operaciones por ID.
• Query params requeridos, como tenantId.

Qué Revisar En El Código

Leer desde main estos archivos o equivalentes:

package.json
src/main.ts
src/app.module.ts
src/app.controller.ts
src/<modulo>/<modulo>.module.ts
src/<modulo>/domain/entities/*.ts
src/<modulo>/domain/repositories/*.ts
src/<modulo>/application/use-cases/*.ts
src/<modulo>/infraestructure/http/*.ts
src/<modulo>/infraestructure/dto/request/*.ts
src/<modulo>/infraestructure/dto/response/*.ts
src/<modulo>/infraestructure/moongose/models/*.ts
src/<modulo>/infraestructure/repositories/*.ts
src/lambda.ts

Nota: algunos repos usan carpetas llamadas infraestructure y moongose. Documentar los nombres tal como existen en el código.

Criterios De Redacción

• Escribir en español.
• Usar nombres reales de rutas, clases, DTOs, providers y campos.
• Evitar URLs locales o productivas de conexión.
• Evitar valores reales de variables de entorno.
• Usar ejemplos genéricos como tenant-123, ana@example.com o IDs ficticios.
• Documentar observaciones técnicas sólo si salen del código en main.
• No asumir validaciones: confirmar si existe ValidationPipe global y cómo está configurado.
• No asumir CORS: revisar main.ts y lambda.ts.

Validación

Después de editar la documentación, ejecutar:

docker compose run --rm docs mkdocs build --strict

El build debe pasar antes de entregar. El warning informativo de Material for MkDocs sobre MkDocs 2.0 no bloquea la documentación actual.

También conviene buscar posibles filtraciones:

rg -n "mongodb://|host.docker|localhost:[0-9]+|password|secret|credencial|MONGODB_URI=.*://" docs/apis

Si aparecen coincidencias, revisar que no sean valores reales ni URLs de conexión.

Plantilla De Navegación

Agregar cada nueva API así:

- APIs:
    - Nombre API:
        - Resumen: apis/nombre-api/index.md
        - Configuración: apis/nombre-api/configuracion.md
        - Arquitectura: apis/nombre-api/arquitectura.md
        - Modelo de datos: apis/nombre-api/modelo-datos.md
        - API REST: apis/nombre-api/api-rest.md
        - Despliegue Lambda: apis/nombre-api/despliegue-lambda.md

APIs Ya Documentadas

API	Ruta
Suppliers	docs/apis/suppliers/
Customers	docs/apis/customers/