Passer au contenu principal
Ajoutez un champ 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.

Générer une section à partir d’une spécification

Ajoutez un champ openapi à un élément de navigation sans pages. Chaque endpoint de la spécification obtient une page dans cet élément.
docs.json
Mintlify regroupe les pages générées par tag. Si une opération a plusieurs tags, elle va dans le groupe de son premier tag. Les opérations sans tag vont dans un groupe nommé API Reference. Pour savoir comment les pages obtiennent leurs titres et leurs URL, consultez URL et titres des endpoints.

Renommer les groupes de tags

Par défaut, le libellé d’un groupe est le name de son tag. Pour afficher un libellé différent, ajoutez x-group au tag. L’URL utilise toujours le name du tag.
Si un tag n’a pas de 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.

Imbriquer des groupes avec des hiérarchies de tags

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 aussi x-group ou x-displayName, l’extension l’emporte, x-group en premier.
  • kind : contrôle la façon dont Mintlify utilise le tag.
    • nav ou aucun kind : crée un groupe de navigation.
    • badge : affiche le summary du tag, ou son name s’il n’y a pas de summary, 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.
Dans cet exemple, l’endpoint List plants apparaît sous Store > Plants dans la barre latérale avec une pastille Beta. Si une opération a plusieurs tags, Mintlify la place selon le premier tag avec 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.

Lister des endpoints précis

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
Si vous listez un endpoint d’une spécification, seuls les endpoints listés obtiennent des pages, y compris ceux des éléments enfants. Mintlify n’ajoute pas les autres. Les éléments de navigation enfants héritent de la spécification de leur parent, sauf s’ils définissent leur propre openapi :
docs.json
Pour lister un endpoint sans spécification par défaut, placez le chemin de la spécification avant la méthode :
docs.json
Mintlify traite toute entrée de pages qui ne correspond pas à une opération comme un chemin de fichier. Les méthodes HTTP doivent être en majuscules.

Utiliser plusieurs spécifications

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.

Organiser une grande spécification

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.json dans les groupes de votre choix. Vous gardez ainsi un contrôle total, mais vous devez ajouter vous-même les nouveaux endpoints à docs.json.

Masquer ou exclure des endpoints

Ajoutez 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.