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.
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 entrue.copy: copia el nodo seleccionado por otra expresión JSONPath en cada nodo seleccionado. Requiere Overlay 1.1.
docs-overlay.yaml
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.
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
https. Hacer referencia a la misma especificación con listas de overlays distintas en diferentes lugares hace que la compilación falle.
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.
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
openapi: "POST /credit/accounts".
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.