MoreLogin publica una versión de instantánea del contrato legible por máquina en el info.version de cada documento OpenAPI. La versión usa el formato de calendario YYYY-MM-DD e identifica el contrato de documentación, no un segmento de versión en la URL de la petición.
| Cambio | Clasificación | Tratamiento en la documentación |
|---|---|---|
| Añadir un campo de petición o respuesta opcional, una operación o un valor de enumeración | Aditivo | Registrar en el changelog y actualizar todas las especificaciones localizadas |
| Aclarar descripciones o corregir un ejemplo sin cambiar el comportamiento en ejecución | Corrección de documentación | Registrar cuando cambie la guía de integración |
| Hacer obligatorio un campo opcional, eliminar o renombrar un campo u operación, restringir valores aceptados o cambiar la semántica establecida | Ruptura | Ofrecer una vía de migración y un contrato versionado por separado antes de la eliminación |
Marcar una operación con deprecated: true | Obsolescencia | Documentar el reemplazo, la fecha de anuncio y la fecha prevista de eliminación cuando esté aprobada |
Los clientes deberían ignorar los campos de respuesta y los valores de enumeración desconocidos cuando su lógica de negocio lo permita. Esto reduce las roturas por versiones aditivas.
La operación OpenAPI es la ubicación legible por máquina con autoridad. Una operación obsoleta debe incluir:
deprecated: true- una descripción que nombre el reemplazo o indique que no existe
- una entrada de anuncio en el changelog de la API
- una fecha prevista de eliminación solo después de que los responsables de producto y del gateway la aprueben
Actualmente no se garantiza ningún periodo mínimo universal de obsolescencia. Hasta que se publique explícitamente una fecha de eliminación, los clientes deberían tratar la operación como soportada pero planificar la migración.
El comportamiento en ejecución sigue teniendo autoridad. OpenAPI, los ejemplos, las copias localizadas, el manifiesto de comportamiento de operaciones y el changelog se verifican juntos en CI para evitar la desviación del contrato.
Superar la puerta de calidad del repositorio demuestra que los archivos OpenAPI, ejemplos, enlaces, copias localizadas y artefactos de gobierno son coherentes dentro del repositorio.
La comprobación de páginas renderizadas demuestra que las rutas representativas de la documentación cargan y se muestran sin errores del cliente.
Solo una prueba de humo con credenciales contra la API desplegada puede demostrar que el comportamiento de producción coincide con el contrato publicado. Este repositorio no ejecuta esa prueba de forma predeterminada, por lo que las notas de versión deben indicar por separado cuándo se realizó la verificación de producción.