x-mint.
Les overlays s’appliquent après l’analyse d’une spécification et avant sa validation : les pages d’endpoints générées, la navigation, les références de frontmatter openapi et mint validate utilisent donc tous le document transformé. Les versions 1.0 et 1.1 de l’Overlay Specification sont prises en charge.
Un document d’overlay comporte une version overlay, un objet info avec un title et une version, et un tableau actions. Chaque action sélectionne des nœuds avec une expression target JSONPath RFC 9535 et applique un modificateur :
update: fusionne une valeur dans chaque nœud ciblé. Les objets sont fusionnés récursivement, les tableaux reçoivent la valeur en ajout et les valeurs primitives sont remplacées.remove: supprime chaque nœud ciblé lorsqu’il vauttrue.copy: copie le nœud sélectionné par une autre expression JSONPath dans chaque nœud ciblé. Nécessite Overlay 1.1.
docs-overlay.yaml
extends relie un overlay à une spécification pour la découverte automatique. Définissez-le sur un chemin relatif au fichier d’overlay, ou sur l’URL exacte qu’utilise votre docs.json pour une spécification hébergée.
Listez les overlays avec la forme objet du champ openapi, qui fonctionne partout où openapi est accepté, y compris dans des tableaux. Les overlays s’appliquent dans l’ordre où vous les listez.
docs.json
https. Référencer la même spécification avec des listes overlays différentes à plusieurs endroits fait échouer la compilation.
Tout fichier JSON ou YAML de votre dépôt comportant une clé overlay de premier niveau est traité comme un document d’overlay. Si son champ extends correspond à l’une de vos spécifications, l’overlay s’applique automatiquement à cette spécification. Les overlays découverts automatiquement s’appliquent dans l’ordre alphabétique de leurs chemins de fichiers. Les overlays sans champ extends ne s’appliquent jamais automatiquement.
Une liste overlays explicite remplace la découverte automatique pour cette spécification. Définissez "overlays": [] pour désactiver tous les overlays d’une spécification, y compris ceux découverts automatiquement.
Les overlays explicites et découverts automatiquement échouent différemment. Si un overlay explicite ne parvient pas à se charger ou à s’appliquer, la spécification échoue à la validation et le déploiement signale une erreur de spécification. Si un overlay découvert automatiquement échoue, il est ignoré et la spécification est publiée sans lui.
L’Overlay Specification ne propose pas d’action de déplacement. Pour renommer un chemin, créez le nouveau chemin avec update, copiez-y l’élément de chemin existant avec copy, puis supprimez l’ancien chemin avec remove.
rename-overlay.yaml
openapi: "POST /credit/accounts".
Dans mint dev, modifier ou supprimer un fichier d’overlay recompile les spécifications concernées. mint validate et mint openapi-check valident le document transformé : les erreurs font donc référence à votre spécification après l’application des overlays.