`.
Le Guide OpenAPI de Swagger porte sur OpenAPI v3.0, mais quasiment toutes les informations
s’appliquent à la v3.1. Pour plus d’informations sur les différences entre la v3.0
et la v3.1, consultez [Migrer d’OpenAPI 3.0 à
3.1.0](https://www.openapis.org/blog/2021/02/16/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 Terrain de jeu API, ajoutez un champ `servers` à votre document OpenAPI avec l’URL de base de votre API.
```json
{
"servers": [
{
"url": "https://api.example.com/v1"
}
]
}
```
Dans un document OpenAPI, les différents endpoints d’API sont définis par leurs chemins, comme `/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](https://swagger.io/docs/specification/api-host-and-base-path/) dans la documentation OpenAPI.
Le Terrain de jeu API utilise ces URL de serveur pour déterminer où envoyer les requêtes. Si vous spécifiez plusieurs serveurs, un menu déroulant permettra aux utilisateurs de passer d’un serveur à l’autre. Si vous ne spécifiez aucun serveur, le Terrain de jeu API utilisera le mode simple, car il ne peut pas envoyer de requêtes sans URL de base.
Si votre API comporte des endpoints disponibles à des URL différentes, vous pouvez [remplacer le champ server](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers) pour un chemin ou une opération donnée.
### Spécifier l’authentification
Pour activer l’authentification dans votre documentation API et le Terrain de jeu API, configurez les champs `securitySchemes` et `security` dans votre document OpenAPI. Les descriptions d’API et le Terrain de jeu API ajouteront des champs d’authentification en fonction des configurations de sécurité de votre document OpenAPI.
Ajoutez un champ `securitySchemes` pour définir comment les utilisateurs s’authentifient.
Cet exemple montre une configuration pour l’authentification bearer.
```json
{
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
}
```
Ajoutez un champ `security` pour rendre l’authentification obligatoire.
```json
{
"security": [
{
"bearerAuth": []
}
]
}
```
Les types d’authentification courants incluent :
* [API Keys](https://swagger.io/docs/specification/authentication/api-keys/) : clés transmises via l’en-tête, la requête ou le cookie.
* [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/) : jetons JWT ou OAuth.
* [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/) : nom d’utilisateur et mot de passe.
Si différents endpoints de votre API requièrent des méthodes d’authentification différentes, vous pouvez [remplacer le champ security](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.) pour une opération donnée.
Pour plus d’informations sur la définition et l’application de l’authentification, consultez [Authentication](https://swagger.io/docs/specification/authentication/) dans la documentation OpenAPI.
## Extension `x-mint`
L’extension `x-mint` est une extension OpenAPI personnalisée qui offre un contrôle accru sur la manière dont votre documentation d’API est générée et affichée.
### Métadonnées
Remplacez les métadonnées par défaut des pages d’API générées en ajoutant `x-mint: metadata` à n’importe quelle opération. Vous pouvez utiliser tout champ de métadonnées valide dans le frontmatter `MDX`, à l’exception de `openapi` :
```json {7-13}
{
"paths": {
"/users": {
"get": {
"summary": "Obtenir la liste des utilisateurs",
"description": "Récupérer une liste d’utilisateurs",
"x-mint": {
"metadata": {
"title": "Lister tous les utilisateurs",
"description": "Récupérer des données d’utilisateurs paginées avec des options de filtrage",
"og:title": "Afficher une liste d’utilisateurs",
}
},
"parameters": [
{
// Configuration du paramètre
}
]
}
}
}
}
```
### Contenu
Ajoutez du contenu avant la documentation API générée automatiquement à l’aide de `x-mint: content` :
```json {6-8}
{
"paths": {
"/users": {
"post": {
"summary": "Créer un utilisateur",
"x-mint": {
"content": "## Prérequis\n\nCet endpoint nécessite des droits administrateur et est soumis à un taux limite.\n\nLes adresses e-mail des utilisateurs doivent être uniques dans l’ensemble du système."
},
"parameters": [
{
// Parameter configuration
}
]
}
}
}
}
```
L’extension `content` prend en charge tous les composants MDX de Mintlify ainsi que leur mise en forme.
### Href
Modifiez l’URL de la page de point de terminaison dans votre documentation à l’aide de `x-mint: href` :
```json {6-8, 14-16}
{
"paths": {
"/legacy-endpoint": {
"get": {
"summary": "Ancien endpoint",
"x-mint": {
"href": "/deprecated-endpoints/legacy-endpoint"
}
}
},
"/documented-elsewhere": {
"post": {
"summary": "Endpoint spécial"
"x-mint": {
"href": "/guides/special-endpoint-guide"
}
}
}
}
}
```
Lorsque `x-mint: href` est présent, l’entrée de navigation renvoie directement à l’URL spécifiée au lieu de générer une page d’API.
### MCP
Exposez sélectivement des endpoints comme outils Model Context Protocol (MCP) à l’aide de `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.
Indique s’il faut exposer l’endpoint en tant qu’outil MCP. Prend le pas sur la configuration au niveau du fichier.
Le nom de l’outil MCP.
La description de l’outil MCP.
```json Selective enablement {6-9} wrap
{
"paths": {
"/users": {
"post": {
"summary": "Create user",
"x-mint": {
"mcp": {
"enabled": true
},
// ...
}
}
},
"/users": {
"delete": {
"summary": "Delete user (admin only)",
// No `x-mint: mcp` so this endpoint is not exposed as an MCP tool
// ...
}
}
}
}
```
```json Global enablement {3-5, 9-13} wrap
{
"openapi": "3.1.0",
"x-mcp": {
"enabled": true // All endpoints are exposed as MCP tools by default
},
"paths": {
"/api/admin/delete": {
"delete": {
"x-mint": {
"mcp": {
"enabled": false // Disable MCP for this endpoint
}
},
"summary": "Delete resources"
}
}
}
}
```
Pour en savoir plus, consultez [Model Context Protocol](/fr/ai/model-context-protocol).
## Remplir automatiquement les pages API
Ajoutez un champ `openapi` à n’importe quel é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, en tant que sections API dédiées ou 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 ont les valeurs de métadonnées par défaut suivantes :
* `title` : Le champ `summary` de l’opération, s’il est présent. S’il n’y a pas de `summary`, le titre est généré à partir de la méthode HTTP et de l’endpoint.
* `description` : Le champ `description` de l’opération, s’il est présent.
* `version` : La valeur `version` de l’ancre ou de l’onglet parent, si elle est présente.
* `deprecated` : Le champ `deprecated` de l’opération. Si `true`, un badge « 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 des endpoints spécifiques de vos pages API générées automatiquement, ajoutez la
propriété [x-hidden](/fr/api-playground/customization/managing-page-visibility#x-hidden)
à l’opération dans votre spécification OpenAPI.
Il existe deux approches pour ajouter des pages d’endpoint à votre documentation :
1. **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.
2. **Endpoints sélectifs** : Référencez des endpoints spécifiques dans votre navigation, aux côtés d’autres pages.
### Sections API dédiées
Générez des sections API dédiées en ajoutant un champ `openapi` à un élément de navigation, sans autres pages. Tous les endpoints de la spécification seront inclus :
```json {5}
"navigation": {
"tabs": [
{
"tab": "Référence de l’API",
"openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
}
]
}
```
Vous pouvez utiliser plusieurs spécifications OpenAPI dans différentes sections de navigation :
```json {8-11, 15-18}
"navigation": {
"tabs": [
{
"tab": "Référence de l’API",
"groups": [
{
"group": "Utilisateurs",
"openapi": {
"source": "/path/to/openapi-1.json",
"directory": "api-reference"
}
},
{
"group": "Admin",
"openapi": {
"source": "/path/to/openapi-2.json",
"directory": "api-reference"
"directory": "api-reference"
}
]
}
]
}
```
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 défini, elles sont enregistrées par défaut dans le répertoire `api-reference`
de votre dépôt.
### Points de terminaison sélectionnés
Si vous souhaitez mieux contrôler l’emplacement des points de terminaison dans votre documentation, vous pouvez référencer des points de terminaison précis dans votre navigation. Cette approche vous permet de générer des pages pour des endpoints d’API aux côtés d’autres contenus.
#### Définir une spécification OpenAPI par défaut
Configurez une spécification OpenAPI par défaut pour un élément de navigation, puis référencez des points de terminaison précis dans le champ `pages` :
```json {12, 15-16}
"navigation": {
"tabs": [
{
"tab": "Démarrage",
"pages": [
"quickstart",
"installation"
]
},
{
"tab": "Référence de l’API",
"openapi": "/path/to/openapi.json",
"pages": [
"api-overview",
"GET /users",
"POST /users",
"guides/authentication"
]
}
]
}
```
Toute entrée de page correspondant au format `METHOD /path` générera une page API pour cet endpoint à partir de la spécification OpenAPI par défaut.
#### Héritage de la spécification OpenAPI
Les spécifications OpenAPI sont héritées dans la hiérarchie de navigation. Les éléments de navigation enfants héritent de la spécification OpenAPI de leur parent, sauf s’ils définissent la leur :
```json {3, 7-8, 11, 13-14}
{
"group": "Référence de l’API",
"openapi": "/path/to/openapi-v1.json",
"pages": [
"overview",
"authentication",
"GET /users",
"POST /users",
{
"group": "Commandes",
"openapi": "/path/to/openapi-v2.json",
"pages": [
"GET /orders",
"POST /orders"
]
}
]
}
```
#### Points de terminaison individuels
Faites référence à des points de terminaison spécifiques sans définir de spécification OpenAPI par défaut en incluant le chemin du fichier :
```json {5-6}
"navigation": {
"pages": [
"introduction",
"guides-utilisateur",
"/path/to/openapi-v1.json POST /users",
"/path/to/openapi-v2.json GET /orders"
]
}
```
Cette approche est utile lorsque vous avez besoin d’endpoints individuels issus de différentes spécifications ou si vous souhaitez n’inclure que certains endpoints.
## Créer des fichiers `MDX` pour les pages API
Pour contrôler chaque page d’endpoint individuellement, créez des pages `MDX` pour chaque opération. Cela vous permet de personnaliser les métadonnées de page, d’ajouter du contenu, d’omettre certaines opérations ou de réorganiser les pages dans votre navigation, au niveau de chaque page.
Voir un [exemple de page MDX OpenAPI de MindsDB](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx?plain=1) et son rendu dans leur [documentation en ligne](https://docs.mindsdb.com/rest/databases/create-databases).
### Spécifier les fichiers manuellement
Créez une page `MDX` pour chaque endpoint et indiquez quelle opération OpenAPI afficher via le 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 Terrain de jeu 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.
Si vous voulez référencer un fichier OpenAPI externe, ajoutez l’URL du fichier à votre `docs.json`.
```mdx Example
---
title: "Get users"
description: "Returns all plants from the system that the user has access to"
openapi: "/path/to/openapi-1.json GET /users"
deprecated: true
version: "1.0"
---
```
```mdx Format
---
title: "title of the page"
description: "description of the page"
openapi: openapi-file-path method path
deprecated: boolean (not required)
version: "version-string" (not required)
---
```
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`
Utilisez notre [scraper](https://www.npmjs.com/package/@mintlify/scraping) Mintlify pour générer automatiquement des pages `MDX` pour les documents OpenAPI volumineux.
Votre document OpenAPI doit être valide, sinon les fichiers ne seront pas
générés automatiquement.
Le scraper génère :
* Une page `MDX` pour chaque opération dans le champ `paths` de votre document OpenAPI.
* Si votre document OpenAPI est en version 3.1+, une page `MDX` pour chaque opération dans le champ `webhooks` de votre document OpenAPI.
* Un tableau d’entrées de navigation que vous pouvez ajouter à votre `docs.json`.
```bash
npx @mintlify/scraping@latest openapi-file
```
```bash
npx @mintlify/scraping@latest openapi-file -o api-reference
```
Ajoutez l’option `-o` pour spécifier un dossier où 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
Vous pouvez créer des pages individuelles pour n’importe quel schéma OpenAPI défini dans le champ `components.schemas` d’un document OpenAPI :
```mdx Example
---
openapi-schema: OrderItem
---
```
```mdx Format
---
openapi-schema: "schema-key"
---
```
## Webhooks
Les webhooks sont des rappels HTTP que votre API envoie pour informer des systèmes externes lorsqu’un événement survient. Les webhooks sont pris en charge dans les documents OpenAPI 3.1+.
### Définir des webhooks dans votre spécification OpenAPI
Ajoutez un champ `webhooks` à votre document OpenAPI, en plus du champ `paths`.
Pour plus d’informations sur la définition des webhooks, consultez [Webhooks](https://spec.openapis.org/oas/v3.1.0#oasWebhooks) dans la documentation OpenAPI.
### Référencer des webhooks dans des fichiers MDX
Lors de la création de pages MDX pour des webhooks, utilisez `webhook` au lieu de méthodes HTTP comme `GET` ou `POST` :
```mdx
---
title: "Exemple de webhook"
description: "Déclenché lorsqu’un événement survient"
openapi: "path/to/openapi-file webhook example-webhook-name"
---
```
Le nom du webhook doit correspondre exactement à la clé définie dans le champ `webhooks`
de votre spécification OpenAPI.