Passer au contenu principal
Les pages d’endpoints générées tirent leur titre, leur description, leurs paramètres et leurs réponses de votre spécification OpenAPI. Pour modifier ce qu’affiche une page, vous pouvez :
  • Ajouter l’extension x-mint à l’opération dans votre spécification. Vos pages restent générées, et les modifications sont conservées avec votre spécification.
  • Créer une page MDX pour l’endpoint. Utilisez cette option pour quelques pages qui nécessitent une mise en page personnalisée, ou pour tester des modifications sur une page.
Pour modifier l’URL d’une page, consultez URL et titres des endpoints.

Remplacer les métadonnées de la page

Ajoutez x-mint.metadata à une opération pour remplacer le frontmatter de la page. Vous pouvez utiliser n’importe quel champ valide dans le frontmatter MDX, sauf openapi.
Utilisez x-mint.metadata pour définir par endpoint l’affichage du playground, les groupes d’accès ou une pastille tag dans la barre latérale.

Ajouter du contenu à une page

Ajoutez du contenu Markdown et MDX avant la documentation d’API générée avec x-mint.content. Le contenu prend en charge tous les composants Mintlify.

Réduire les champs du playground

Pour que les champs d’objets imbriqués soient réduits par défaut dans le playground, définissez x-mint.playground.expand sur false sur une opération. Les sections Authorization, Headers, Query, Path et Body, ainsi que l’objet de corps de premier niveau, restent développés : les lecteurs ne développent que les champs imbriqués dont ils ont besoin. Par défaut, les champs d’objets sont développés.
Pour contrôler l’affichage des champs facultatifs sur tous les endpoints, utilisez api.optional dans votre docs.json.

Ajouter des pastilles de paramètres

Étiquetez les paramètres avec des pastilles personnalisées à l’aide de x-mint.pre et x-mint.post sur n’importe quel schéma. Les pastilles de pre apparaissent avant le nom du paramètre, et celles de post après, à côté des pastilles intégrées comme required, read-only et write-only. Chaque chaîne du tableau devient sa propre pastille.
Pour afficher un champ de votre spécification sous forme de pastille sur chaque paramètre qui le possède, listez la clé du champ dans api.params.post de votre docs.json :
docs.json
Avec cette configuration, une propriété comme { "type": "string", "nullable": true, "x-internal": "admin" } affiche les pastilles nullable et admin à côté de son nom. Les pastilles post apparaissent dans cet ordre : pastilles intégrées, puis pastilles de api.params.post, puis pastilles x-mint.post propres à chaque propriété.

Créer des pages MDX pour les endpoints

Créez une page MDX pour un endpoint lorsque vous voulez un contrôle total sur une page tout en conservant les paramètres et réponses générés. Définissez le champ de frontmatter openapi sur l’opération que la page documente.
La valeur openapi doit être une chaîne unique qui référence un seul endpoint. Si vous la définissez comme une liste d’endpoints ou une autre valeur qui n’est pas une chaîne, le déploiement échoue. La méthode et le chemin doivent correspondre exactement à votre spécification OpenAPI. Ajoutez la page à votre navigation comme n’importe quelle autre page. Ne listez pas aussi la même opération, comme "GET /users", dans votre navigation.
Incluez toujours le chemin du fichier de spécification lorsque votre dépôt contient plusieurs spécifications OpenAPI.Mintlify téléverse chaque spécification OpenAPI de votre dépôt de documentation, même si docs.json ne la référence pas. Si une page MDX utilise openapi: "METHOD /path" sans chemin de fichier, Mintlify recherche une opération correspondante dans toutes les spécifications téléversées. Si plusieurs spécifications contiennent la même méthode et le même chemin, la première correspondance dans l’ordre alphabétique des noms de fichiers l’emporte.Pour éviter une mauvaise correspondance, incluez le chemin du fichier dans le frontmatter, générez plutôt les pages depuis docs.json, ou supprimez les spécifications dont vous n’avez plus besoin.
Pour créer des fichiers MDX pour chaque endpoint d’une spécification, utilisez le scraper de Mintlify. Ajoutez -o pour choisir le dossier de sortie. Sans cette option, les fichiers sont créés dans le répertoire courant.
Pour reconvertir des pages d’endpoints MDX existantes en pages générées, consultez Migrer les pages d’API MDX vers OpenAPI.

Créer des pages pour les modèles de données

Créez une page pour un schéma de components.schemas de votre spécification avec le champ de frontmatter openapi-schema.
Si des schémas de plusieurs spécifications portent le même nom, incluez le chemin du fichier :