Repository navigation
OpenAPI y Swagger
BuenOrigen Backend utiliza OpenAPI/Swagger para publicar la descripción de las operaciones REST disponibles. Es una referencia para los equipos Frontend y Mobile, que consumen los contratos de la API.
NestJS integra Swagger con @nestjs/swagger. La descripción puede utilizar decoradores como:
| Decorador | Finalidad |
|---|---|
@ApiTags() |
Agrupar operaciones por dominio |
@ApiOperation() |
Explicar el propósito del endpoint |
@ApiParam() |
Describir parámetros de ruta |
@ApiQuery() |
Describir parámetros de consulta |
@ApiOkResponse() |
Documentar respuestas satisfactorias |
@ApiNotFoundResponse() |
Describir recursos inexistentes |
@ApiProperty() |
Exponer propiedades de DTOs |
@ApiPropertyOptional() |
Documentar propiedades opcionales |
La lista explica el rol de los decoradores: no afirma que cada decorador se utilice en todos los controllers.
Los decoradores OpenAPI no sustituyen los pipes, class-validator ni el tratamiento de excepciones. Las correcciones de contratos y validaciones REST integradas hasta el PR #59 deben quedar reflejadas en la documentación generada.
Para parámetros numéricos, la documentación debe expresar la obligatoriedad, el tipo y las restricciones definidas en los controllers. Por ejemplo, un parámetro cantidad no válido puede generar 400 Bad Request cuando esa validación forma parte del endpoint.
El material previo del proyecto sitúa Swagger en /api, habitualmente http://localhost:3000/api cuando se utiliza el puerto 3000. La URL real depende de la configuración de ejecución y de las variables del entorno.
- Productos: búsqueda, ofertas, ventas, nuevos productos, detalle, Huella Verde, valoraciones y relacionados.
- Subcategorías: navegación por categoría, listado y populares de una subcategoría.
- Emprendedores: directorio, perfil público y productos asociados.
- Clientes: consultar los controllers y documentación generada actuales; no inferir autenticación ni rutas
/meretiradas.
- Endpoints documenta rutas y funcionalidades.
- DTOs describe las estructuras de transferencia.
- Funcionalidades Backend diferencia requerimientos de UX/UI e implementaciones.
- Componentes Transversales explica validaciones, middleware y filtros de excepciones.
Al cambiar una operación, mantener sincronizados controller, DTO, respuestas HTTP, Swagger y las páginas de Wiki correspondientes. Las rutas propuestas por UX/UI no deben exponerse como operaciones reales hasta implementarse.