Passer au contenu principal
OpenAPI est une spécification destinée à décrire des API. Mintlify prend en charge les documents OpenAPI 3.0+ 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 spécification OpenAPI valide au format JSON ou YAML conforme à la spécification OpenAPI 3.0+. Vous pouvez référencer plusieurs spécifications OpenAPI pour créer des pages pour votre API. Soit vous organisez des sections pour chaque spécification dans votre navigation, soit vous référencez des endpoints spécifiques provenant de différentes spécifications.
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.
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.

​
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. 
{
  "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 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 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.
1

Définissez votre méthode d’authentification.

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.
{
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
2

Appliquez l’authentification à vos endpoints.

Ajoutez un champ security pour rendre l’authentification obligatoire.
{
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
Les types d’authentification courants incluent :
  • Clés d’API : pour les clés transmises via l’en-tête, les paramètres de requête ou les cookies.
  • Bearer : pour les jetons JWT ou OAuth.
  • Basic : 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 pour une opération donnée. Pour plus d’informations sur la définition et l’application de l’authentification, consultez la section Authentication de la documentation OpenAPI.

​
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 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 n’importe quel champ de métadonnées valide dans le front matter MDX, à l’exception de openapi. 
{
  "paths": {
    "/users": {
      "get": {
        "summary": "Obtenir les utilisateurs",
        "description": "Récupérer la liste des utilisateurs",
        "x-mint": {
          "metadata": {
            "title": "Lister tous les utilisateurs",
            "description": "Récupérer les données utilisateur paginées avec des options de filtrage",
            "og:title": "Afficher la liste des utilisateurs"
          }
        },
        "parameters": [
          {
            // Configuration des paramètres
          }
        ]
      }
    }
  }
}

​
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. 
{
  "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\n<Note>Les adresses e-mail des utilisateurs doivent être uniques dans l'ensemble du système.</Note>"
        },
        "parameters": [
          {
            // Configuration des paramètres
          }
        ]
      }
    }
  }
}

​
Href

Modifiez l’URL de la page de point de terminaison dans votre documentation avec x-mint: href. Lorsque x-mint: href est présent, l’entrée de navigation renvoie directement vers l’URL spécifiée au lieu de générer une page d’API. 
{
  "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"
        }
      }
    }
  }
}

​
MCP

Exposez sélectivement des points de terminaison en tant qu’outils Model Context Protocol (MCP) à l’aide de x-mint: mcp. N’activez que ceux qui sont sûrs pour un accès public via des outils d’IA.
​
mcp
object
La configuration MCP pour le point de terminaison.
{
  "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
        // ...
      }
    }
  }
}
Pour en savoir plus, consultez Model Context Protocol.

​
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 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 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, 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 à 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 sont inclus. 
"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. 
"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ù 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, 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. 
"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 spécifications OpenAPI sont héritées au sein de 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. 
{
  "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. 
"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. 
---
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"
---
La méthode et le chemin doivent correspondre exactement à votre spécification OpenAPI. Si vous avez plusieurs spécifications OpenAPI, incluez le chemin du fichier dans votre référence. Les URL OpenAPI externes peuvent être référencées 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 de Mintlify. 
npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o <folder-name>
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. 
---
openapi-schema: OrderItem
---
Si vous avez des schémas portant le même nom dans plusieurs fichiers, indiquez le fichier OpenAPI : 
---
openapi-schema: en-schema.json OrderItem
---

​
Webhooks

Les webhooks sont des callbacks HTTP que votre API envoie pour avertir des systèmes externes lorsque des événements se produisent. Les webhooks sont pris en charge dans les documents OpenAPI 3.1+. 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 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 : 
---
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.