Estado actual
La referencia publicada se genera desde el OpenAPI servido por el backend productivo. Eso implica:- cambios nuevos aparecen primero en OpenAPI
- las rutas legacy pueden convivir con rutas RESTful
- los consumidores deben preferir endpoints modernos cuando existan ambos
Regla de compatibilidad
Cuando detectes dos rutas equivalentes:- usa la RESTful
- evita rutas con verbos en el path
- manten la legacy solo para compatibilidad de integraciones existentes
Buen criterio para integradores
- encapsula el acceso a endpoints legacy
- no distribuyas rutas viejas en nuevos consumidores
- usa esta documentacion y la pestaña API como contrato vigente
Cambios a monitorear
- nuevos tags o modulos en OpenAPI
- cambios en DTOs de request/response
- nuevos codigos de error
- endpoints que pasen de legacy a recomendados
Recomendacion operativa
Antes de releases importantes:- revisar
generated/openapi.json - validar cambios en la pestaña API
- revisar flujos comunes afectados
- comunicar cambios breaking a consumidores internos