Saltar al contenido principal
Usa OpenAPI Overlays para modificar una especificación OpenAPI sin editar su archivo de origen. Los overlays son archivos JSON o YAML independientes que describen una lista ordenada de cambios, lo que resulta útil cuando una especificación la genera otra herramienta o la mantiene otro equipo. Los usos comunes incluyen renombrar rutas, reemplazar URLs de servidores, eliminar endpoints internos y agregar extensiones x-mint. Los overlays se aplican después de analizar una especificación y antes de validarla, por lo que las páginas de endpoints generadas, la navegación, las referencias del frontmatter openapi y mint validate usan el documento transformado. Se admiten las versiones 1.0 y 1.1 de Overlay Specification.

Crear un documento de overlay

Un documento de overlay tiene una versión overlay, un objeto info con un title y una version, y un array actions. Cada acción selecciona nodos con una expresión target de JSONPath RFC 9535 y aplica un modificador:
  • update: fusiona un valor en cada nodo seleccionado. Los objetos se fusionan de forma recursiva, los arrays añaden el valor y los valores primitivos se reemplazan.
  • remove: elimina cada nodo seleccionado cuando se establece en true.
  • copy: copia el nodo seleccionado por otra expresión JSONPath en cada nodo seleccionado. Requiere Overlay 1.1.
docs-overlay.yaml
El campo opcional extends vincula un overlay a una especificación para el descubrimiento automático. Establécelo en una ruta relativa al archivo de overlay, o en la URL exacta que usa tu docs.json para una especificación alojada.

Hacer referencia a overlays en tu docs.json

Enumera los overlays con la forma de objeto del campo openapi, que funciona en cualquier lugar donde se acepte openapi, incluso dentro de arrays. Los overlays se aplican en el orden en que los enumeras.
docs.json
Las rutas de los overlays deben apuntar a archivos dentro de tu repositorio de documentación, y las URLs de los overlays deben usar https. Hacer referencia a la misma especificación con listas de overlays distintas en diferentes lugares hace que la compilación falle.

Descubrir overlays automáticamente

Cualquier archivo JSON o YAML de tu repositorio con una clave overlay de nivel superior se trata como un documento de overlay. Si su campo extends se resuelve a una de tus especificaciones, el overlay se aplica automáticamente a esa especificación. Los overlays descubiertos automáticamente se aplican en orden alfabético según la ruta de sus archivos. Los overlays sin un campo extends nunca se aplican automáticamente. Una lista overlays explícita reemplaza el descubrimiento automático para esa especificación. Establece "overlays": [] para deshabilitar todos los overlays de una especificación, incluidos los descubiertos automáticamente. Los overlays explícitos y los descubiertos automáticamente fallan de forma distinta. Si un overlay explícito no se carga o no se aplica, la especificación no supera la validación y el despliegue informa de un error de especificación. Si falla un overlay descubierto automáticamente, se omite y la especificación se publica sin él.

Renombrar una ruta

Overlay Specification no tiene una acción de mover. Para renombrar una ruta, crea la nueva ruta con update, copia en ella el elemento de ruta existente con copy y, después, elimina la ruta anterior con remove.
rename-overlay.yaml
Haz referencia a la especificación transformada en toda tu documentación. Por ejemplo, el frontmatter de las páginas debe usar la ruta posterior al overlay: openapi: "POST /credit/accounts".

Probar overlays localmente

En mint dev, editar o eliminar un archivo de overlay vuelve a compilar las especificaciones afectadas. mint validate y mint openapi-check validan el documento transformado, así que los errores hacen referencia a tu especificación después de aplicar los overlays.