OpenAPI est une spécification pour décrire des API. Mintlify prend en charge les documents OpenAPI 3.0+ pour générer une documentation API interactive et la maintenir à jour.

​
Ajouter un fichier de spécification OpenAPI

Pour documenter vos endpoints avec OpenAPI, vous avez besoin d’un document OpenAPI valide, au format JSON ou YAML, conforme à la spécification OpenAPI 3.0+. Vous pouvez créer des pages API à partir d’un ou de plusieurs documents OpenAPI.

​
Décrire votre API

Nous recommandons les ressources suivantes pour apprendre et rédiger vos documents OpenAPI.
Le Guide OpenAPI de Swagger concerne 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, consultez l’article 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 API, ajoutez un champ servers à votre document OpenAPI avec l’URL de base de votre API. 
{
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}
Dans un document OpenAPI, les différents points de terminaison de l’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 dans la documentation OpenAPI. Le bac à sable 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 basculer entre les serveurs. Si vous ne spécifiez pas de serveur, le bac à sable API utilisera 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 remplacer le champ servers pour un chemin ou une opération donnés.

​
Spécifier l’authentification

Pour activer l’authentification dans votre documentation API et le Bac à sable API, configurez les champs securitySchemes et security dans votre document OpenAPI. Les descriptions d’API et le Bac à sable API ajouteront des champs d’authentification en fonction des paramètres de sécurité définis dans votre document OpenAPI.
1

Définissez votre méthode d’authentification.

Ajoutez un champ securitySchemes pour définir comment les utilisateurs s’authentifient.Cet exemple montre une configuration pour l’authentification 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 API : pour les clés transmises via l’en-tête, la requête ou le cookie.
  • 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 des méthodes d’authentification différentes, vous pouvez surcharger le champ security pour une opération donnée. Pour en savoir plus sur la définition et l’application de l’authentification, consultez la section Authentication de 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 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 valable dans le frontmatter MDX, à l’exception de openapi : 
{
  "paths": {
    "/users": {
      "get": {
        "summary": "Get users",
        "description": "Retrieve a list of users",
        "x-mint": {
          "metadata": {
            "title": "List all users",
            "description": "Fetch paginated user data with filtering options",
            "og:title": "Display a list of users"
          }
        },
        "parameters": [
          {
            // Configuration des paramètres
          }
        ]
      }
    }
  }
}

​
Contenu

Ajoutez du contenu avant la documentation API générée automatiquement à l’aide de x-mint: content : 
{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create user",
        "x-mint": {
          "content": "## Prerequisites\n\nThis endpoint requires admin privileges and has rate limiting.\n\n<Note>User emails must be unique across the system.</Note>"
        },
        "parameters": [
          {
            // Configuration du paramètre
          }
        ]
      }
    }
  }
}
L’extension content prend en charge tous les composants MDX (Mintlify) et le formatage.

​
Href

Modifiez l’URL de la page de l’endpoint dans votre documentation à l’aide de x-mint: href : 
{
  "paths": {
    "/legacy-endpoint": {
      "get": {
        "summary": "Legacy endpoint",
        "x-mint": {
          "href": "/deprecated-endpoints/legacy-endpoint"
        }
      }
    },
    "/documented-elsewhere": {
      "post": {
        "summary": "Special endpoint",
        "x-mint": {
          "href": "/guides/special-endpoint-guide"
        }
      }
    }
  }
}
Lorsque 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 API.

​
MCP

Exposez de façon sélective des endpoints en tant qu’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.
​
mcp
object
La configuration MCP de l’endpoint.
{
  "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 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 décider où ces pages apparaissent dans votre structure de navigation, soit dans des 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 utilisent par défaut les métadonnées suivantes :
  • title : Le champ summary de l’opération, s’il est présent. En son absence, 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. S’il est à 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 à 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 ajouter d’autres pages. Tous les endpoints de la spécification seront inclus : 
"navigation": {
  "tabs": [
    {
        "tab": "API Reference",
        "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
    }
  ]
}
Vous pouvez utiliser plusieurs spécifications OpenAPI dans différentes sections de navigation : 
"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Users",
          "openapi": {
            "source": "/path/to/openapi-1.json",
            "directory": "api-reference"
          }
        },
        {
          "group": "Admin",
          "openapi": {
            "source": "/path/to/openapi-2.json",
            "directory": "api-reference"
          }
        }
      ]
    }
  ]
}
Le champ directory est facultatif et précise l’emplacement où les pages API générées sont enregistrées dans votre dépôt de documentation. S’il n’est pas défini, la valeur par défaut est le répertoire api-reference de votre dépôt.

​
Endpoints sélectifs

Si vous souhaitez mieux contrôler l’emplacement des endpoints dans votre documentation, vous pouvez référencer des endpoints spécifiques dans votre navigation. Cette approche vous permet de générer des pages pour des endpoints d’API à côté 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 endpoints spécifiques dans le champ pages : 
"navigation": {
  "tabs": [
    {
      "tab": "Getting started",
      "pages": [
        "quickstart",
        "installation"
      ]
    },
    {
      "tab": "API reference",
      "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 des spécifications OpenAPI

Les spécifications OpenAPI sont transmises le long de la hiérarchie de navigation. Les éléments enfants héritent de la spécification OpenAPI de leur parent, sauf s’ils définissent la leur : 
{
  "group": "API reference",
  "openapi": "/path/to/openapi-v1.json",
  "pages": [
    "overview",
    "authentication",
    "GET /users",
    "POST /users",
    {
      "group": "Orders",
      "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 : 
"navigation": {
  "pages": [
    "introduction",
    "user-guides",
    "/path/to/openapi-v1.json POST /users",
    "/path/to/openapi-v2.json GET /orders"
  ]
}
Cette approche est utile lorsque vous avez besoin de points de terminaison individuels issus de différentes spécifications ou si vous souhaitez n’inclure que certains points de terminaison.

​
Créez des fichiers MDX pour les pages API

Pour contrôler chaque page d’endpoint, créez une page MDX par opération. Vous pourrez ainsi personnaliser les métadonnées de page, ajouter du contenu, omettre certaines opérations ou réorganiser les pages dans la navigation, au niveau de chaque page. Consultez un exemple de page OpenAPI en MDX de MindsDB et voyez comment elle s’affiche dans leur documentation en ligne.

​
Spécifier les fichiers manuellement

Créez une page MDX pour chaque endpoint et indiquez quelle opération OpenAPI afficher en utilisant le champ openapi dans le frontmatter. Lorsque vous faites référence à une opération OpenAPI de cette manière, le nom, la description, les paramètres, les réponses et le bac à sable API sont automatiquement générés à partir de votre document OpenAPI. Si vous avez plusieurs fichiers OpenAPI, incluez le chemin du fichier dans votre référence pour vous assurer 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 défini ou non 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 souhaitez référencer un fichier OpenAPI externe, ajoutez l’URL du fichier à votre docs.json. 
---
title: "Get users"
description: "Renvoie tous les utilisateurs du système auxquels 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 à 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 Mintlify pour générer automatiquement des pages MDX à partir de 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.
1

Générer des fichiers `MDX`.

npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
2

Spécifier un dossier de sortie.

npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o api-reference
Ajoutez l’option -o pour spécifier un dossier dans lequel écrire 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 distinctes pour n’importe quel schéma OpenAPI défini dans le champ components.schema d’un document OpenAPI : 
---
openapi-schema: OrderItem
---

​
Webhooks

Les webhooks sont des rappels HTTP envoyés par votre API pour notifier des systèmes externes lorsque des événements se produisent. 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 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

Lors de la création de pages MDX pour des webhooks, utilisez webhook plutôt que des méthodes HTTP comme GET ou POST : 
---
title: "Example webhook"
description: "Triggered when an event occurs"
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.