> ## Documentation Index
> Fetch the complete documentation index at: https://adminroletesting-justin-client-exports.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration d’OpenAPI
> Générez une documentation API interactive à partir de fichiers OpenAPI, avec pages d'endpoints automatiques, constructeurs de requêtes et navigation.
OpenAPI est une spécification destinée à décrire des API. Mintlify prend en charge les documents OpenAPI 3.0 et 3.1 pour générer une documentation d’API interactive et la maintenir à jour.
## Ajouter un fichier de spécification OpenAPI
Pour documenter vos endpoints avec OpenAPI, vous avez besoin d'une ou plusieurs spécifications OpenAPI valides au format JSON ou YAML qui respectent la [spécification OpenAPI 3.0 ou 3.1](https://swagger.io/specification/).
Ajoutez des spécifications OpenAPI à votre référentiel de documentation ou hébergez-les en ligne de manière à pouvoir y accéder via une URL. Les spécifications stockées dans votre référentiel sont [proposées au téléchargement](/fr/create/files) à leur chemin sur votre domaine de documentation. Par exemple, `https://your-domain/docs/openapi.json`.
Référencez autant de spécifications OpenAPI que nécessaire dans l'élément `navigation` de votre fichier `docs.json` pour créer des pages pour vos endpoints d'API. Chaque fichier de spécification génère son propre ensemble d'endpoints.
```json Spécification unique theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": "openapi.json"
}
]
}
```
```json Plusieurs spécifications theme={null}
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": [
"openapi/v1.json",
"openapi/v2.json"
]
}
]
}
```
Mintlify prend en charge `$ref` pour les **références internes uniquement** au sein d'un seul document OpenAPI. Les références externes ne sont pas prises en charge.
### Décrivez votre API
Nous recommandons les ressources suivantes pour apprendre et rédiger votre spécification OpenAPI.
* [Guide OpenAPI de Swagger](https://swagger.io/docs/specification/v3_0/basic-structure/) pour apprendre la syntaxe d’OpenAPI.
* [Sources Markdown de la spécification OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/) pour consulter les détails de la dernière version de la spécification OpenAPI.
* [Swagger Editor](https://editor.swagger.io/) pour modifier, valider et déboguer votre document OpenAPI.
* [Mint CLI](https://www.npmjs.com/package/mint) pour valider votre document OpenAPI avec la commande : `mint validate`.
Le guide OpenAPI de Swagger porte sur OpenAPI v3.0, mais la quasi-totalité des informations s’applique à v3.1. Pour en savoir plus sur les différences entre v3.0 et v3.1, consultez l’article du blog OpenAPI [Migrating from OpenAPI 3.0 to 3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0).
### Spécifiez l’URL de base de votre API
Pour activer l’aire de jeu de l’API, ajoutez un champ `servers` à votre spécification OpenAPI avec l’URL de base de votre API.
```json theme={null}
{
"servers": [
{
"url": "https://api.example.com/v1"
}
]
}
```
Dans une spécification OpenAPI, les différents points de terminaison (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 en savoir plus sur la configuration du champ `servers`, consultez la page [API Server and Base Path](https://swagger.io/docs/specification/api-host-and-base-path/) de la documentation OpenAPI.
Le bac à sable de l’API utilise ces URL de serveur pour déterminer où envoyer les requêtes. Si vous spécifiez plusieurs serveurs, un menu déroulant permet aux utilisateurs de basculer entre eux. Si vous ne spécifiez aucun serveur, le bac à sable de l’API utilise le mode simple, puisqu’il ne peut pas envoyer de requêtes sans URL de base.
Si votre API comporte des points de terminaison accessibles à différentes URL, vous pouvez [surcharger le champ `servers`](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers) pour un chemin ou une opération donnés.
### Spécifier l’authentification
Pour activer l’authentification dans votre documentation et votre environnement de test API, configurez les champs `securitySchemes` et `security` dans votre spécification OpenAPI. Les descriptions d’API et l’environnement de test API ajoutent des champs d’authentification en fonction des paramètres de sécurité de votre spécification OpenAPI.
Ajoutez un champ `securitySchemes` pour définir la manière dont les utilisateurs s’authentifient.
Cet exemple montre une configuration pour l’authentification de type Bearer.
```json theme={null}
{
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
}
```
Ajoutez un champ `security` pour rendre l’authentification obligatoire.
```json theme={null}
{
"security": [
{
"bearerAuth": []
}
]
}
```
Les types d’authentification courants incluent :
* [Clés d’API](https://swagger.io/docs/specification/authentication/api-keys/) : pour les clés transmises via l’en-tête, les paramètres de requête ou les cookies.
* [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/) : pour les jetons JWT ou OAuth.
* [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/) : pour le nom d’utilisateur et le mot de passe.
Si différents endpoints de votre API nécessitent différentes méthodes d’authentification, 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 la section [Authentication](https://swagger.io/docs/specification/authentication/) de la documentation OpenAPI.
#### Définir des valeurs par défaut pour les schémas de sécurité
Utilisez l’extension `x-default` sur un schéma de sécurité pour pré-remplir le champ d’authentification dans le playground de l’API. Cela est utile pour fournir des valeurs d’exemple ou des identifiants de test qui aident les utilisateurs à démarrer rapidement.
```json {6} theme={null}
{
"components": {
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"x-default": "your-api-key-here"
}
}
}
}
```
L’extension `x-default` prend en charge les types de schéma de sécurité `apiKey` et `http` bearer. La valeur apparaît comme entrée par défaut dans les champs d’authentification du playground.
Vous pouvez également utiliser `x-default` sur n’importe quelle propriété de schéma dans votre spécification OpenAPI pour définir une valeur par défaut dans le playground de l’API sans affecter le champ `default` dans la définition du schéma.
## Permettez aux visiteurs de télécharger votre spécification
Activez une entrée « Télécharger la spécification d’API » dans le [menu contextuel de la page](/fr/organize/settings-structure#contextual) en ajoutant `"download-spec"` à `contextual.options` dans votre `docs.json` :
```json theme={null}
"contextual": {
"options": ["copy", "download-spec", "chatgpt", "claude"]
}
```
Lorsque l’option est activée, un clic dessus télécharge directement votre spécification OpenAPI. Les déploiements comportant plusieurs spécifications les reçoivent regroupées dans `api-specs.zip`. L’option est masquée pour les déploiements protégés par `auth` ou `userAuth` afin d’éviter la fuite du contenu des spécifications depuis une documentation authentifiée.
## Personnalisez les pages de vos endpoints
Personnalisez les pages de vos endpoints en ajoutant l’extension `x-mint` à votre spécification OpenAPI. L’extension `x-mint` vous offre un contrôle supplémentaire sur la manière dont votre documentation d’API se génère et s’affiche.
### 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 n’importe quel champ de métadonnées valide dans le front matter MDX, à l’exception de `openapi`.
```json {7-14} theme={null}
{
"paths": {
"/users": {
"get": {
"summary": "Get users",
"description": "Retrieve a list of users",
"x-mint": {
"metadata": {
"title": "List all users",
"sidebarTitle": "List users",
"description": "Récupérer les données utilisateur paginées avec des options de filtrage",
"og:title": "Display a list of users"
}
},
"parameters": [
{
// Parameter configuration
}
]
}
}
}
}
```
Vous pouvez également contrôler l’affichage du playground pour chaque endpoint à l’aide des champs metadata `playground` et `groups` :
```json {7-11} theme={null}
{
"paths": {
"/admin/users": {
"post": {
"summary": "Créer un utilisateur administrateur",
"x-mint": {
"metadata": {
"playground": "auth",
"groups": ["admin"],
"public": true
}
}
}
}
}
}
```
Cette configuration rend la page accessible au public tout en réservant l’espace de test interactif aux utilisateurs authentifiés du groupe `admin`.
### Contenu
Ajoutez du contenu avant la documentation API générée automatiquement à l’aide de `x-mint: content`. L’extension `x-mint: content` est compatible avec tous les composants MDX de Mintlify ainsi que leur mise en forme.
```json {6-8} theme={null}
{
"paths": {
"/users": {
"post": {
"summary": "Créer un utilisateur",
"x-mint": {
"content": "## Prérequis\n\nCe point de terminaison nécessite des privilèges administrateur et est soumis à une limitation du débit.\n\nLes adresses e-mail des utilisateurs doivent être uniques dans l'ensemble du système."
},
"parameters": [
{
// Configuration des paramètres
}
]
}
}
}
}
```
### href
Définissez l’URL de la page de point de terminaison générée automatiquement à l’aide de `x-mint: href`. Lorsque `x-mint: href` est présent, la page d’API générée utilise l’URL spécifiée au lieu de l’URL par défaut générée automatiquement.
```json {6-8, 14-16} theme={null}
{
"paths": {
"/legacy-endpoint": {
"get": {
"summary": "Point de terminaison obsolète",
"x-mint": {
"href": "/deprecated-endpoints/legacy-endpoint"
}
}
},
"/documented-elsewhere": {
"post": {
"summary": "Point de terminaison spécial",
"x-mint": {
"href": "/guides/special-endpoint-guide"
}
}
}
}
}
```
### Pastilles de paramètre
Annotez les paramètres dans la référence de l'API et dans le playground avec des libellés de pastilles personnalisés à l'aide de `x-mint.pre` et `x-mint.post` sur n'importe quel schéma. Les pastilles pre s'affichent avant le nom du paramètre et les pastilles post s'affichent après, aux côtés des pastilles intégrées de Mintlify telles que `required`, `read-only` et `write-only`.
Les deux champs acceptent un tableau de chaînes. Chaque chaîne devient sa propre pastille.
```json {7-10} theme={null}
{
"components": {
"schemas": {
"User": {
"properties": {
"email": {
"type": "string",
"x-mint": {
"pre": ["PII"],
"post": ["indexed", "unique"]
}
}
}
}
}
}
}
```
Pour faire apparaître des champs arbitraires de la spécification OpenAPI sous forme de pastilles sur chaque paramètre sans modifier chaque schéma, configurez [`api.params.post`](/fr/organize/settings-api#api-params) dans votre `docs.json`. Listez les clés des champs que vous souhaitez afficher, et Mintlify lit chaque valeur depuis le schéma et affiche automatiquement les pastilles correspondantes.
```json theme={null}
{
"api": {
"params": {
"post": ["nullable", "x-internal"]
}
}
}
```
Avec cette configuration, une propriété telle que `{ "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 (`read-only`, `write-only`), puis pastilles définies par la configuration `api.params.post`, puis pastilles `x-mint.post` propres à la propriété.
### Noms d'affichage des groupes
Définissez un nom d'affichage personnalisé pour le groupe de navigation d'un tag à l'aide de l'extension `x-group` sur un objet tag. Par défaut, Mintlify utilise le `name` du tag à la fois comme libellé du groupe de navigation et comme segment du chemin URL. L'extension `x-group` remplace le libellé du groupe tout en conservant le nom du tag pour l'URL.
Cela est utile lorsque vous souhaitez un nom de groupe lisible qui diffère du tag utilisé dans les chemins de votre API.
```json {4-9} theme={null}
{
"tags": [
{
"name": "user-management",
"description": "Endpoints for managing users",
"x-group": "User Management"
}
],
"paths": {
"/users": {
"get": {
"tags": ["user-management"],
"summary": "List users"
}
}
}
}
```
Dans cet exemple, le groupe de navigation s'affiche sous le nom "User Management", mais l'URL de la page générée utilise toujours le nom du tag `user-management` comme segment de chemin.
## Remplir automatiquement les pages d'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, soit en tant que sections API dédiées, soit aux côtés d’autres pages.
Le champ `openapi` accepte soit un chemin dans votre dépôt de documentation, soit une URL vers un document OpenAPI hébergé.
Lorsque vous utilisez une URL pour votre spécification OpenAPI, les modifications de la spécification ne déclenchent pas de push Git, donc vos docs ne se redéploient pas automatiquement. Pour garder vos docs synchronisés, appelez l’endpoint d’API [Trigger deployment](/fr/api/update/trigger) dans la même action CI qui génère ou met à jour votre spécification. Ainsi, vos docs se mettent à jour automatiquement sans avoir à déclencher manuellement un déploiement depuis le tableau de bord.
Les pages d’endpoint générées ont les 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`, Mintlify génère le titre à 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`, une étiquette « obsolète » apparaît à 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 d’API générées automatiquement, ajoutez la propriété [x-hidden](/fr/api-playground/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 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 d’API dédiées
Générez des sections d’API dédiées en ajoutant un champ `openapi` à un élément de navigation, sans autres pages. Tous les points de terminaison de la spécification apparaissent dans la section générée.
```json {5} theme={null}
"navigation": {
"tabs": [
{
"tab": "Référence API",
"openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
}
]
}
```
Pour organiser plusieurs spécifications OpenAPI dans des sections distinctes de votre documentation, assignez chaque spécification à un groupe différent dans votre hiérarchie de navigation. Chaque groupe peut référencer sa propre spécification OpenAPI.
```json {8-11, 15-18} theme={null}
"navigation": {
"tabs": [
{
"tab": "Référence API",
"groups": [
{
"group": "API Utilisateurs",
"openapi": {
"source": "/path/to/users-openapi.json",
"directory": "users-api-reference"
}
},
{
"group": "API Administration",
"openapi": {
"source": "/path/to/admin-openapi.json",
"directory": "admin-api-reference"
}
}
]
}
]
}
```
Le champ `directory` est facultatif et indique où Mintlify stocke les pages d’API générées dans votre dépôt de documentation. S’il n’est pas défini, le répertoire par défaut est `api-reference` à la racine de votre dépôt.
### Points de terminaison sélectifs
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 points de terminaison d’API aux côtés d’autres contenus. Vous pouvez également utiliser cette approche pour combiner des points de terminaison provenant de différentes spécifications OpenAPI.
#### Définir une spécification OpenAPI par défaut
Configurez une spécification OpenAPI par défaut pour un élément de navigation. Référencez ensuite des points de terminaison spécifiques dans le champ `pages`.
```json {12, 15-16} theme={null}
"navigation": {
"tabs": [
{
"tab": "Démarrage",
"pages": [
"quickstart",
"installation"
]
},
{
"tab": "Référence 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ère une page d’API pour ce point de terminaison à partir de la spécification OpenAPI par défaut.
#### Héritage de la spécification OpenAPI
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} theme={null}
{
"group": "Référence API",
"openapi": "/path/to/openapi-v1.json",
"pages": [
"aperçu",
"authentification",
"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 d’accès au fichier. Vous pouvez référencer des points de terminaison issus de plusieurs spécifications OpenAPI dans une même section de documentation.
```json {5-6} theme={null}
"navigation": {
"pages": [
"introduction",
"user-guides",
"/path/to/users-openapi.json POST /users",
"/path/to/orders-openapi.json GET /orders"
]
}
```
Cette approche est utile lorsque vous avez besoin de points de terminaison individuels provenant de différentes spécifications, que vous souhaitez inclure uniquement certains points de terminaison, ou que vous voulez les intégrer aux côtés d’autres types de documentation.
## Créer des pages MDX à partir de votre spécification OpenAPI
Pour un contrôle plus fin de chaque page d’endpoint, créez des pages MDX à partir de votre spécification OpenAPI. Vous pourrez ainsi personnaliser les métadonnées et le contenu des pages, ainsi que réorganiser ou exclure des pages de votre navigation, tout en conservant les paramètres et réponses générés automatiquement.
Il existe deux façons de documenter votre spécification OpenAPI avec des pages MDX distinctes :
* Documenter les endpoints avec le champ `openapi` dans le frontmatter.
* Documenter les modèles de données avec le champ `openapi-schema` dans le frontmatter.
### Documenter les endpoints
Créez une page pour chaque endpoint et indiquez quelle opération OpenAPI afficher en utilisant le champ `openapi` dans le frontmatter.
```mdx Example theme={null}
---
title: "Récupérer des utilisateurs"
description: "Renvoie toutes les plantes du système auxquelles l'utilisateur a accès"
openapi: "/path/to/openapi-1.json GET /users"
deprecated: true
version: "1.0"
---
```
```mdx Format theme={null}
---
title: "titre de la page"
description: "description de la page"
openapi: chemin-vers-fichier-openapi méthode chemin
deprecated: booléen (facultatif)
version: "chaîne-de-version" (facultatif)
---
```
La méthode et le chemin doivent correspondre exactement à votre spécification OpenAPI. Si vous avez plusieurs spécifications OpenAPI, incluez le chemin vers la spécification correcte dans votre référence. Vous pouvez également référencer des URL OpenAPI externes dans `docs.json`.
#### Générer automatiquement des pages d’endpoint
Pour générer automatiquement des fichiers MDX à partir de votre spécification OpenAPI, utilisez le [scraper](https://www.npmjs.com/package/@mintlify/scraping) de Mintlify.
```bash theme={null}
npx @mintlify/scraping@latest openapi-file -o
```
Ajoutez l’option `-o` pour préciser un dossier où déposer les fichiers. Si aucun dossier n’est indiqué, les fichiers seront créés dans le répertoire de travail.
### Documenter les modèles de données
Créez une page pour chaque structure de données définie dans `components.schemas` de votre spécification OpenAPI en utilisant le champ `openapi-schema` dans le frontmatter.
```mdx Example theme={null}
---
openapi-schema: OrderItem
---
```
```mdx Format theme={null}
---
openapi-schema: "openapi-file-path schema-key"
---
```
Si vous avez des schémas portant le même nom dans plusieurs fichiers, indiquez le fichier OpenAPI :
```mdx Example theme={null}
---
openapi-schema: en-schema.json OrderItem
---
```
```mdx Format theme={null}
---
openapi-schema: "path-to-schema-file schema-key"
---
```
## Webhooks
Les webhooks sont des callbacks HTTP que votre API envoie pour avertir des systèmes externes lorsque des événements se produisent. Les documents OpenAPI 3.1+ prennent en charge les webhooks.
Ajoutez un champ `webhooks` à votre document OpenAPI, en parallèle du champ `paths`.
Pour en savoir plus sur la définition des webhooks, consultez la section [Webhooks](https://spec.openapis.org/oas/v3.1.0#oasWebhooks) de la documentation OpenAPI.
Pour créer une page MDX pour un webhook (OpenAPI 3.1+), utilisez `webhook` au lieu d’une méthode HTTP :
```mdx theme={null}
---
title: "Webhook de mise à jour de commande"
description: "Déclenché lorsqu'une commande est mise à jour"
openapi: "openapi.json webhook orderUpdated"
---
```
Le nom du webhook doit correspondre exactement à la clé du champ `webhooks` de votre spécification OpenAPI.
## Callbacks
Les callbacks décrivent des requêtes hors bande que votre API envoie à une URL fournie par l'appelant, par exemple des notifications d'événements liées à une opération spécifique. Lorsqu'une opération OpenAPI définit des `callbacks`, Mintlify les affiche sur la page du endpoint dans une section repliable entre le corps de la requête et la section de réponse. Chaque callback affiche sa méthode HTTP, son expression et réutilise les mêmes composants de corps et de réponse que l'opération principale.
Vous n'avez rien à configurer pour afficher les callbacks. Si votre spécification OpenAPI définit des `callbacks` sur une opération, ils apparaissent automatiquement sur la page du endpoint générée.
Pour en savoir plus sur la définition des callbacks, consultez la section [Callbacks](https://spec.openapis.org/oas/v3.1.0#callback-object) de la documentation OpenAPI.
Exemple de définition de callback sur une opération :
```yaml theme={null}
paths:
/subscribe:
post:
summary: S'abonner aux événements
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
callbackUrl:
type: string
format: uri
responses:
"201":
description: Abonnement créé
callbacks:
orderUpdated:
"{$request.body#/callbackUrl}":
post:
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
orderId:
type: string
status:
type: string
responses:
"200":
description: Callback reçu
```