openapi à n’importe quel élément de navigation de votre docs.json, comme un onglet, une ancre ou un groupe, pour générer des pages d’endpoints à partir d’une spécification. Le champ openapi accepte un chemin dans votre dépôt de documentation ou l’URL d’une spécification hébergée.
Vous pouvez ajouter des endpoints de deux façons :
- Générer une section à partir d’une spécification entière. Chaque endpoint obtient une page, regroupée par tag. Utilisez cette option pour la plupart des références d’API.
- Lister des endpoints précis. Seuls les endpoints que vous listez obtiennent des pages, dans l’ordre où vous les listez, à côté de vos autres pages.
openapi à un élément de navigation sans pages. Chaque endpoint de la spécification obtient une page dans cet élément.
docs.json
name de son tag. Pour afficher un libellé différent, ajoutez x-group au tag. L’URL utilise toujours le name du tag.
x-group, Mintlify utilise son extension x-displayName comme libellé : les spécifications qui utilisent déjà x-displayName n’ont besoin d’aucune modification. Si un tag possède les deux, x-group l’emporte.
Dans les documents OpenAPI 3.2, les tags peuvent déclarer les champs parent, kind et summary. Mintlify les utilise pour construire des groupes imbriqués. Les documents OpenAPI 3.0 et 3.1 conservent un groupe plat par tag.
parent: imbrique le groupe du tag dans le groupe du tag parent.summary: définit le libellé du groupe. Si un tag possède aussix-groupoux-displayName, l’extension l’emporte,x-groupen premier.kind: contrôle la façon dont Mintlify utilise le tag.navou aucunkind: crée un groupe de navigation.badge: affiche lesummarydu tag, ou sonnames’il n’y a pas desummary, sous forme de pastille à côté de l’endpoint dans la barre latérale. Les tags de type badge ne créent pas de groupe.- Toute autre valeur, comme
audience: ne crée ni groupe ni pastille.
kind: nav. S’il n’y en a pas, Mintlify utilise le premier tag déclaré sans kind, puis le premier tag non déclaré dans tags. Pour définir une pastille différente pour un endpoint, utilisez tag dans x-mint.metadata, qui a priorité sur les tags de type badge.
La validation échoue si deux tags portent le même nom, si un parent référence un tag qui n’existe pas ou si les références parent forment un cycle.
Pour choisir quels endpoints obtiennent des pages et où ils apparaissent, définissez un openapi par défaut sur un élément de navigation et listez les endpoints dans ses pages sous la forme METHOD /path. Vous pouvez mélanger des endpoints avec d’autres pages.
docs.json
openapi :
docs.json
docs.json
pages qui ne correspond pas à une opération comme un chemin de fichier. Les méthodes HTTP doivent être en majuscules.
Pour générer des pages à partir de plusieurs spécifications, placez chaque spécification sur son propre élément de navigation et donnez à chacune son propre directory. Si vous définissez openapi comme un tableau, Mintlify génère des pages uniquement à partir de la première spécification du tableau.
docs.json
directory définit le dossier dans l’URL de chaque page générée. Si deux spécifications partagent un directory et produisent la même URL de page, une page remplace l’autre sans avertissement. Consultez URL et titres des endpoints.
Mintlify ne lit pas l’extension x-tagGroups. Pour une spécification comportant de nombreux tags, choisissez une approche :
- Une spécification par section. Divisez la spécification en un fichier par domaine de produit, ou utilisez des overlays pour supprimer les opérations qui n’appartiennent pas à chaque section, puis donnez à chacune sa propre section.
- Hiérarchies de tags. Passez à OpenAPI 3.2 et imbriquez les tags sous des tags parents.
- Lister les endpoints. Listez chaque endpoint dans votre
docs.jsondans les groupes de votre choix. Vous gardez ainsi un contrôle total, mais vous devez ajouter vous-même les nouveaux endpoints àdocs.json.
x-hidden ou x-excluded à une opération ou à un webhook pour l’exclure de votre navigation générée :
x-hidden: true: l’endpoint obtient une page, mais la page n’apparaît pas dans la navigation. Toute personne disposant de l’URL peut l’ouvrir. Utilisez-le pour les endpoints vers lesquels vous créez des liens depuis d’autres pages ou que vous partagez avec des utilisateurs précis.x-excluded: true: l’endpoint n’obtient pas de page. Utilisez-le pour les endpoints internes, ou ceux qui ne sont pas prêts à être documentés.
x-excluded supprime uniquement la page. Si les visiteurs peuvent accéder à votre fichier de spécification, les endpoints exclus y figurent toujours.
Pour n’afficher des endpoints qu’à certains groupes d’utilisateurs, ajoutez x-mint.groups à l’opération. Consultez Filtrage du contenu OpenAPI.