[Gobierno de APIs] Soportar OpenAPI 3.1 en la plantilla corporativa de microservicios

[karluiz]

Contexto

Los servicios creados con la plantilla NETCoreMongoGR publican su contrato de
API en una versión anterior del estándar (OpenAPI 3.0, generado con tooling
legado). El estándar vigente es OpenAPI 3.1, alineado completamente con
JSON Schema, y es el formato que esperan el catálogo corporativo de APIs, las
herramientas de validación y los consumidores automatizados y agénticos
de nuestros contratos.

Relacionada con la actualización de la plantilla por obsolescencia (#1).

Historia

Como responsable de Gobierno de APIs del grupo,
quiero que todo microservicio creado con la plantilla publique su contrato
en OpenAPI 3.1 válido,
para que nuestras APIs sean interoperables, validables automáticamente y
consumibles sin ambigüedad por humanos, herramientas y agentes.

Criterios de aceptación

• El servicio de ejemplo de la plantilla publica su contrato en
  OpenAPI 3.1 y pasa validación automática en el pipeline.
• El contrato refleja fielmente endpoints, modelos y errores reales
  del servicio (nada mantenido a mano que pueda quedar desactualizado).
• La documentación navegable (UI) sigue disponible para los equipos.
• Los consumidores actuales del contrato no se rompen: se mantiene
  compatibilidad o publicación dual durante la transición.
• Queda una guía breve para los equipos: dónde vive el contrato y
  cómo se valida.

Restricciones (guardrails)

• Retirar o reemplazar el formato de contrato que hoy consumen herramientas
  existentes (portal, generadores de clientes, gateway) requiere
  aprobación humana.
• No se modifica el comportamiento de los endpoints: esta misión es de
  contrato y documentación, no de funcionalidad.
• Dependencias solo del catálogo aprobado.

Definición de done

Spec cumplida, contrato 3.1 validado en el pipeline, documentación accesible,
y traza completa de decisiones disponible para auditoría.