Passer au contenu principal
OpenAPI est une spécification de description d’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’un document OpenAPI valide au format JSON ou YAML conforme à la spécification OpenAPI 3.0+. Vous pouvez créer des pages d’API à partir d’un ou de plusieurs documents OpenAPI.

Décrire votre API

Nous recommandons les ressources suivantes pour apprendre et concevoir vos documents OpenAPI.
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 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 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 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

Pour activer l’Authentification dans votre documentation et votre bac à sable d’API, configurez les champs 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.
{
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
2

Apply authentication to your endpoints.

Ajoutez un champ security pour exiger l’authentification.
{
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
Les types d’authentification courants incluent :
  • 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.
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 Authentication dans la documentation OpenAPI.

Extension x-mint

L’extension 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

Remplacez les metadata 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 metadata valide dans le frontmatter MDX, à l’exception de openapi :
{
  "paths": {
    "/users": {
      "get": {
        "summary": "Obtenir les utilisateurs",
        "description": "Récupérer une liste d'utilisateurs",
        "x-mint": {
          "metadata": {
            "title": "Lister tous les utilisateurs",
            "description": "Récupérer des données utilisateur paginées avec options de filtrage",
            "og:title": "Afficher une liste d'utilisateurs"
          }
        },
        "parameters": [
          {
            // Configuration des paramètres
          }
        ]
      }
    }
  }
}

Contenu

Ajoutez du contenu avant la documentation de l’API générée automatiquement à l’aide de x-mint: content :
{
  "paths": {
    "/users": {
      "post": {
        "summary": "Créer un utilisateur",
        "x-mint": {
          "content": "## Prérequis\n\nCe point de terminaison nécessite des privilèges d'administrateur et est soumis à une limitation de débit.\n\n<Note>Les adresses e-mail des utilisateurs doivent être uniques dans le système.</Note>"
        },
        "parameters": [
          {
            // Configuration des paramètres
          }
        ]
      }
    }
  }
}
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 d’endpoint dans votre documentation à l’aide de x-mint: href :
{
  "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"
        }
      }
    }
  }
}
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 d’API.

MCP

Exposez sélectivement 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.

Renseigner automatiquement les pages d’API

Ajoutez un champ 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 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 du Tab parent, si elle est présente.
  • deprecated : Le champ deprecated de l’opération. Si true, 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.
Deux approches permettent d’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 ciblés : 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 :
"navigation": {
  "tabs": [
    {
        "tab": "Référence API",
        "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": "Référence API",
      "groups": [
        {
          "group": "Utilisateurs",
          "openapi": {
            "source": "/path/to/openapi-1.json",
            "directory": "api-reference"
          }
        },
        {
          "group": "Administrateur",
          "openapi": {
            "source": "/path/to/openapi-2.json",
            "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 précisé, la valeur par défaut est le répertoire api-reference de votre dépôt.

Endpoints ciblés

Lorsque 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 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 endpoints spécifiques dans le champ pages :
"navigation": {
  "tabs": [
    {
      "tab": "Prise en main",
      "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èrera une page API pour cet endpoint en utilisant 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 :
{
  "group": "Référence 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 :
"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’points de terminaison spécifiques provenant de différentes spécifications ou que vous souhaitez n’inclure que certains endpoints.

Créer des fichiers MDX pour les pages d’API

Pour gérer chaque page d’endpoint individuellement, créez une page 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

Créez une page 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.
Si vous souhaitez référencer un fichier OpenAPI externe, ajoutez l’URL du fichier à votre docs.json.
---
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"
---
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 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.
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 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 tout schéma OpenAPI défini dans le champ components.schema d’un document OpenAPI :
---
openapi-schema: OrderItem
---

Webhooks

Les webhooks sont des rappels (callbacks) HTTP que votre API envoie pour informer des systèmes externes lorsque des événements surviennent. 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 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

Lors de la création de pages MDX pour les webhooks, utilisez webhook plutôt que des méthodes HTTP comme GET ou POST :
---
title: "Exemple de webhook"
description: "Déclenché lorsqu'un événement se produit"
openapi: "path/to/openapi-file webhook example-webhook-name"
---
Le nom du webhook doit correspondre exactement à la key définie dans le champ webhooks de votre spécification OpenAPI.
I