Ajouter un fichier de spécification OpenAPI
Décrire votre API
- Swagger’s OpenAPI Guide pour apprendre la syntaxe OpenAPI.
- The OpenAPI specification Markdown sources pour consulter les détails de la dernière spécification OpenAPI.
- Swagger Editor pour modifier, valider et déboguer votre document OpenAPI.
- The Mint CLI pour valider votre document OpenAPI avec la commande :
mint openapi-check <openapiFilenameOrUrl>
.
Swagger’s OpenAPI Guide est destiné à OpenAPI v3.0, mais presque toutes les informations
s’appliquent à la v3.1. Pour plus d’informations sur les différences entre la v3.0
et la v3.1, voir Migrating from OpenAPI 3.0 to
3.1.0
sur le blog OpenAPI.
Spécifier l’URL de votre API
Pour activer des fonctionnalités Mintlify comme le bac à sable d’API, ajoutez un champservers
à votre document OpenAPI avec l’URL de base de votre API.
/users/{id}
ou simplement /
. L’URL de base indique où ces chemins doivent être ajoutés. Pour plus d’informations sur la configuration du champ servers
, consultez API Server and Base Path dans la documentation OpenAPI.
Le bac à sable d’API utilise ces URL de serveur pour déterminer où envoyer les requêtes. Si vous spécifiez plusieurs serveurs, une liste déroulante permettra aux utilisateurs de basculer entre eux. Si vous ne spécifiez pas de serveur, le bac à sable d’API utilisera le mode simple puisqu’il ne peut pas envoyer de requêtes sans URL de base.
Si votre API expose des endpoints à différentes URL, vous pouvez remplacer le champ server pour un chemin ou une opération donnée.
Spécifier l’authentification
securitySchemes
et security
dans votre document OpenAPI. Les descriptions d’API et le bac à sable d’API ajouteront des champs d’authentification en fonction des configurations de sécurité définies dans votre document OpenAPI.
1
Define your authentication method.
Ajoutez un champ
securitySchemes
pour définir comment les utilisateurs s’authentifient.Cet exemple montre une configuration pour l’authentification Bearer.2
Apply authentication to your endpoints.
Ajoutez un champ
security
pour exiger l’authentification.- API Keys : pour les clés dans l’en-tête, la requête ou le cookie.
- Bearer : pour les JWT (JSON Web Token) ou les jetons OAuth.
- Basic : pour le nom d’utilisateur et le mot de passe.
Extension x-mint
x-mint
est une extension OpenAPI personnalisée qui offre un contrôle supplémentaire sur la manière dont la documentation de votre API est générée et affichée.
Metadata
x-mint: metadata
à n’importe quelle opération. Vous pouvez utiliser n’importe quel champ de metadata valide dans le frontmatter MDX
, à l’exception de openapi
:
Contenu
x-mint: content
:
content
prend en charge tous les composants MDX de Mintlify ainsi que leur mise en forme.
Href
x-mint: href
:
x-mint: href
est présent, l’entrée de navigation pointe directement vers l’URL spécifiée au lieu de générer une page d’API.
MCP
x-mint: mcp
. N’activez que les endpoints sûrs pour un accès public via des outils d’IA.
La configuration MCP de l’endpoint.
Renseigner automatiquement les pages d’API
openapi
à tout élément de navigation dans votre docs.json
pour générer automatiquement des pages pour les endpoints OpenAPI. Vous pouvez contrôler l’emplacement de ces pages dans votre structure de navigation, soit en sections API dédiées, soit aux côtés d’autres pages.
Le champ openapi
accepte soit un chemin de fichier dans votre dépôt de documentation, soit une URL vers un document OpenAPI hébergé.
Les pages d’endpoint générées comportent par défaut les metadata suivantes :
title
: Le champsummary
de l’opération, s’il est présent. S’il n’y a pas desummary
, le titre est généré à partir de la méthode HTTP et de l’endpoint.description
: Le champdescription
de l’opération, s’il est présent.version
: La valeurversion
de l’ancre ou du Tab parent, si elle est présente.deprecated
: Le champdeprecated
de l’opération. Sitrue
, un libellé « obsolète » apparaîtra à côté du titre de l’endpoint dans la navigation latérale et sur la page de l’endpoint.
Pour exclure certains endpoints de vos pages d’API générées automatiquement, ajoutez la propriété
x-hidden
à l’opération dans votre spécification OpenAPI.
- Sections API dédiées : Référencez des spécifications OpenAPI dans des éléments de navigation pour créer des sections API dédiées.
- Endpoints ciblés : Référencez des endpoints spécifiques dans votre navigation, aux côtés d’autres pages.
Sections API dédiées
openapi
à un élément de navigation, sans autres pages. Tous les endpoints de la spécification seront inclus :
Le champ
directory
est facultatif et indique où les pages d’API générées sont
stockées dans votre dépôt de documentation. S’il n’est pas précisé, la valeur par défaut est le répertoire api-reference
de votre dépôt.Endpoints ciblés
Définir une spécification OpenAPI par défaut
pages
:
METHOD /path
génèrera une page API pour cet endpoint en utilisant la spécification OpenAPI par défaut.
Héritage de la spécification OpenAPI
Points de terminaison individuels
Créer des fichiers MDX
pour les pages d’API
MDX
par opération. Vous pouvez ainsi personnaliser les metadata de la page, ajouter du contenu, omettre certaines opérations ou réorganiser les pages dans la navigation au niveau de chaque page.
Voir un exemple de page MDX OpenAPI de MindsDB et son rendu dans leur documentation en ligne.
Spécifier les fichiers manuellement
MDX
pour chaque endpoint et indiquez l’opération OpenAPI à afficher à l’aide du champ openapi
dans le frontmatter.
Lorsque vous référencez une opération OpenAPI de cette manière, le nom, la description, les paramètres, les réponses et le bac à sable d’API sont générés automatiquement à partir de votre document OpenAPI.
Si vous avez plusieurs fichiers OpenAPI, incluez le chemin du fichier dans votre référence pour garantir que Mintlify trouve le bon document OpenAPI. Si vous n’avez qu’un seul fichier OpenAPI, Mintlify le détectera automatiquement.
Cette approche fonctionne que vous ayez ou non défini une spécification OpenAPI
par défaut dans votre navigation. Vous pouvez référencer n’importe quel endpoint
depuis n’importe quelle spécification OpenAPI en incluant le chemin du fichier
dans le frontmatter.
docs.json
.
La méthode et le chemin doivent correspondre exactement à la définition dans
votre spécification OpenAPI. Si l’endpoint n’existe pas dans le fichier OpenAPI,
la page sera vide.
Générer automatiquement des fichiers MDX
MDX
pour les documents OpenAPI volumineux.
Votre document OpenAPI doit être valide, sinon les fichiers ne seront pas générés automatiquement.
- Une page
MDX
pour chaque opération dans le champpaths
de votre document OpenAPI. - Si votre document OpenAPI est en version 3.1+, une page
MDX
pour chaque opération dans le champwebhooks
de votre document OpenAPI. - Un tableau d’entrées de navigation que vous pouvez ajouter à votre
docs.json
.
1
Générer des fichiers `MDX`.
2
Spécifier un dossier de sortie.
-o
pour spécifier un dossier dans lequel créer les fichiers. Si aucun dossier n’est spécifié, les fichiers seront créés dans le répertoire de travail.Créer des fichiers MDX
pour les schémas OpenAPI
components.schema
d’un document OpenAPI :
Webhooks
Définir des webhooks dans votre spécification OpenAPI
webhooks
à votre document OpenAPI, en complément du champ paths
.
Pour en savoir plus sur la définition des webhooks, consultez la section Webhooks de la documentation OpenAPI.
Référencer des webhooks dans des fichiers MDX
webhook
plutôt que des méthodes HTTP comme GET
ou POST
:
Le nom du webhook doit correspondre exactement à la key définie dans le champ
webhooks
de votre spécification OpenAPI.