Camaroneras Docs

Apariencia

0035. El spec OpenAPI cubre solo bodies de request, no responses ​

Estado ​

Superada por ADR-0036 (los DTOs de respuesta ya se implementaron; el spec ahora cubre también los responses 2xx).

Contexto ​

Al ejecutar ADR-0034 se habilitó el CLI plugin de @nestjs/swagger esperando que infiriera también el shape de las respuestas. Verificado sobre el openapi.json generado: 0 de 69 responses tienen schema. Causa: los controllers del backend retornan objetos literales { data, message } (ver ADR-0006), no clases DTO de respuesta — TypeScript no preserva esa forma para la metadata de reflexión que usa el plugin, así que no hay de dónde inferir el schema. Los bodies de request sí funcionan bien: ya eran DTOs con @ApiProperty, y el plugin ahora infiere tipos/opcionales/enums directamente del código.

Decisión ​

Esta tarea (camaroneras_docs) deja el spec y la API Reference cubriendo solo bodies de request. Agregar DTOs de respuesta a los ~40 endpoints del backend para que el spec también cubra responses no entra en esta tarea — es cambio de código de negocio por módulo, no documentación. Los *-flow.md de cada módulo conservan sus ejemplos de // response a mano; solo se les quitó el // body (cubierto por el spec).

Consecuencias ​

  • La API Reference (/api/) es fiel para requests, pero no muestra el shape de ninguna respuesta — quien la use debe revisar el *-flow.md del módulo para eso.
  • injectEnvelopeStatusCode (camaroneras_backend/src/common/swagger/build-document.ts) queda implementado para inyectar statusCode en schemas de respuesta inline, pero hoy es un no-op (no hay ninguno) y no resuelve $ref — que es justo la forma que tendrán los DTOs de respuesta reales (@ApiResponse({ type: XDto }) genera un $ref a components.schemas, no un schema inline). Extenderlo para ese caso queda para cuando se implemente la derivada de abajo, no antes.
  • Derivada registrada en el backlog del monorepo ("DTOs de respuesta en el backend") para cuando se decida abordar el spec completo, probablemente una tarea por módulo o un barrido único con un DTO de respuesta genérico.