Configuration d’OpenAPI

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. 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 à 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.

"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "openapi": "openapi.json"
    }
  ]
}

"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 pour apprendre la syntaxe d’OpenAPI.
Sources Markdown de la spécification OpenAPI pour consulter les détails de la dernière version de la spécification OpenAPI.
Swagger Editor pour modifier, valider et déboguer votre document OpenAPI.
Mint CLI 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.

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, des chemins comme /users/{id} ou / identifient les différents points de terminaison (endpoints) d’API. L’URL de base indique où les clients ajoutent ces chemins. 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.

Configurer les téléversements de fichiers

Dans les spécifications OpenAPI 3.1, définissez un téléversement de fichier comme un schéma de type string avec un contentMediaType binaire. Le playground de l’API reconnaît le champ comme un sélecteur de fichier et l’envoie dans une requête multipart/form-data. Utilisez cette configuration lorsqu’un endpoint accepte un fichier dans une requête multipart. Vous pouvez également utiliser contentEncoding pour décrire le codage du contenu du fichier. Une valeur contentEncoding sans contentMediaType binaire reste un champ texte. Pour les fichiers encodés en base64, définissez contentEncoding sur base64 ou base64url. Le playground traite ces deux valeurs comme un fichier base64. Pour les autres valeurs ou en l’absence de valeur, le playground utilise le traitement des fichiers binaires.

{
  "paths": {
    "/imports": {
      "post": {
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "contentMediaType": "application/octet-stream"
                  }
                },
                "required": ["file"]
              }
            }
          }
        }
      }
    }
  }
}

Vous pouvez utiliser des types MIME binaires tels que application/octet-stream, les images, l’audio, la vidéo, les PDF et les archives. Le playground de l’API ne traite pas les types structurés tels que application/json comme des téléversements de fichiers. Les anciennes valeurs format: "binary" et format: "base64" restent prises en charge.

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.

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"
      }
    }
  }
}

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.

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.

{
  "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. Le pré-remplissage pour les schémas de sécurité s’applique de manière inconditionnelle et ne nécessite aucune configuration supplémentaire. Vous pouvez également utiliser x-default sur d’autres propriétés 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. Contrairement aux schémas de sécurité, le pré-remplissage pour les propriétés qui ne sont pas des schémas de sécurité ne prend effet que lorsque api.examples.prefill est défini sur true dans votre docs.json.

Le pré-remplissage depuis x-default sur des propriétés de schéma de type array n’est pas pris en charge actuellement dans le playground de l’API, même lorsque api.examples.prefill est activé.

Transformez votre spécification avec des overlays

Utilisez les overlays OpenAPI pour modifier une spécification OpenAPI sans éditer son fichier source. Les overlays sont des fichiers JSON ou YAML distincts qui décrivent une liste ordonnée de modifications, ce qui est utile lorsqu’une spécification est générée par un autre outil ou maintenue par une autre équipe. Les usages courants incluent le renommage de chemins, le remplacement d’URL de serveur et la suppression d’endpoints internes. Les overlays s’appliquent après l’analyse d’une spécification et avant sa validation, de sorte que les pages d’endpoints générées, la navigation, les références openapi dans le frontmatter et mint validate utilisent tous le document transformé. Les versions 1.0 et 1.1 de la spécification Overlay sont prises en charge.

Créer un document d’overlay

Un document d’overlay comporte une version overlay, un objet info avec un title et une version, et un tableau actions. Chaque action sélectionne des nœuds avec une expression target au format JSONPath RFC 9535 et applique un modificateur :

update : fusionne une valeur dans chaque nœud ciblé. Les objets fusionnent de manière récursive, les tableaux ajoutent la valeur à la fin et les primitives sont remplacées.
remove : supprime chaque nœud ciblé lorsque défini sur true.
copy : copie le nœud sélectionné par une autre expression JSONPath dans chaque nœud ciblé. Nécessite Overlay 1.1.

docs-overlay.yaml

overlay: 1.1.0
info:
  title: Docs adjustments
  version: 1.0.0
extends: ./openapi.json
actions:
  - target: $.info.description
    update: "The public API for Example, Inc."
  - target: $.paths['/internal-metrics']
    remove: true

Le champ facultatif extends associe un overlay à une spécification pour la découverte automatique. Définissez-le sur un chemin relatif au fichier d’overlay, ou sur l’URL exacte que votre docs.json utilise pour une spécification hébergée.

Référencer les overlays dans votre docs.json

Listez les overlays avec la forme objet du champ openapi, qui fonctionne partout où openapi est accepté, y compris à l’intérieur de tableaux. Les overlays s’appliquent dans l’ordre où vous les listez.

"navigation": {
  "tabs": [
    {
      "tab": "API reference",
      "openapi": {
        "source": "openapi.json",
        "overlays": [
          "overlays/rename-paths.yaml",
          "https://example.com/overlays/servers.yaml"
        ]
      }
    }
  ]
}

Les chemins d’overlay doivent pointer vers des fichiers situés dans votre dépôt de documentation, et les URL d’overlay doivent utiliser https. Référencer la même spécification avec des listes overlays différentes à plusieurs endroits fait échouer la génération.

Découverte automatique des overlays

Tout fichier JSON ou YAML de votre dépôt comportant une clé overlay de premier niveau est traité comme un document d’overlay. Si son champ extends correspond à l’une de vos spécifications, l’overlay s’applique automatiquement à cette spécification. Les overlays découverts automatiquement s’appliquent dans l’ordre alphabétique de leurs chemins de fichier. Les overlays sans champ extends ne s’appliquent jamais automatiquement. Une liste overlays explicite remplace la découverte automatique pour cette spécification. Définissez "overlays": [] pour désactiver tous les overlays d’une spécification, y compris ceux découverts automatiquement. Les overlays explicites et découverts automatiquement échouent différemment. Si un overlay explicite ne peut pas être chargé ou appliqué, la spécification échoue à la validation et le déploiement signale une erreur de spécification. Si un overlay découvert automatiquement échoue, il est ignoré et la spécification est publiée sans lui.

Renommer un chemin

La spécification Overlay ne comporte pas d’action de déplacement. Pour renommer un chemin, créez le nouveau chemin avec update, copiez-y l’élément de chemin existant avec copy, puis supprimez l’ancien chemin avec remove.

rename-overlay.yaml

overlay: 1.1.0
info:
  title: Move accounts under credit
  version: 1.0.0
extends: ./openapi.json
actions:
  - target: $.paths
    update:
      /credit/accounts: {}
  - target: $.paths['/credit/accounts']
    copy: $.paths['/accounts']
  - target: $.paths['/accounts']
    remove: true

Référencez la spécification transformée partout dans votre documentation. Par exemple, le frontmatter d’une page doit utiliser le chemin post-overlay : openapi: "POST /credit/accounts". Dans mint dev, la modification ou la suppression d’un fichier d’overlay reconstruit les spécifications concernées. mint validate et mint openapi-check valident le document transformé, de sorte que les erreurs référencent votre spécification après l’application des overlays.

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 en ajoutant "download-spec" à contextual.options dans votre docs.json :

"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. Sur les déploiements protégés par auth ou userAuth, seuls les lecteurs authentifiés peuvent télécharger la spécification.

La spécification OpenAPI téléchargée n’est pas filtrée et ne respecte pas les groupes d’authentification. Tout lecteur authentifié capable d’ouvrir le menu contextuel reçoit la spécification complète, y compris les points de terminaison et schémas qui seraient autrement masqués pour son groupe. N’activez pas download-spec sur un site authentifié si votre spécification OpenAPI contient des points de terminaison ou champs que vous jugez sensibles.

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.

{
  "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 :

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

{
  "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

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.

{
  "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"
        }
      }
    }
  }
}

Réduire les champs du playground

Réduisez par défaut les champs de type objet dans le playground de l’API en utilisant x-mint: playground avec expand: false sur n’importe quelle opération. Les sections de requête telles que Authorization, Headers, Query, Path et Body restent toujours développées, et l’objet body de premier niveau reste développé, mais les champs de type objet imbriqués à l’intérieur commencent réduits afin que les lecteurs ne développent que les champs avec lesquels ils souhaitent interagir. Si expand n’est pas défini, les champs de type objet sont développés par défaut.

{
  "paths": {
    "/users": {
      "get": {
        "summary": "Get users",
        "x-mint": {
          "playground": {
            "expand": false
          }
        }
      }
    }
  }
}

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 définies avec x-mint.pre s’affichent avant le nom du paramètre, et les pastilles définies avec x-mint.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.

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

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

{
  "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é. Les spécifications hébergées doivent être accessibles depuis l’Internet public.

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 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 à l’opération dans votre spécification OpenAPI.

Il existe deux approches pour ajouter des pages d’endpoint à votre documentation :

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.
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.

"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ù 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.

"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.

{
  "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"
---

---
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.

Spécifiez toujours le chemin du fichier OpenAPI lorsque vous avez plusieurs spécifications OpenAPI dans votre référentiel.Mintlify charge chaque spécification OpenAPI de votre référentiel de documentation, même si elle n’est pas référencée dans docs.json. Lorsqu’une page MDX utilise openapi: "MÉTHODE /chemin" sans chemin de fichier, Mintlify recherche une opération correspondante dans toutes les spécifications chargées. Si plus d’une spécification contient la même méthode et le même chemin, la première correspondance l’emporte selon l’ordre alphabétique du nom de fichier, ce qui peut ne pas être la spécification attendue.Pour éviter toute ambiguïté, procédez de l’une des façons suivantes :

Incluez le chemin du fichier de spécification dans le frontmatter : openapi: "chemin/vers/openapi-correct.json POST /v1/endpoint".
Utilisez la génération automatique de pages en référençant le fichier OpenAPI dans docs.json, ce qui associe toujours les endpoints à la bonne spécification.
Supprimez le chemin en conflit de l’autre spécification.
Supprimez de votre référentiel les fichiers OpenAPI dont vous n’avez plus besoin.

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
---

---
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 :

---
openapi-schema: en-schema.json OrderItem
---

---
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 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.

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 de la documentation OpenAPI. Exemple de définition de callback sur une opération :

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

​Ajouter un fichier de spécification OpenAPI

​Décrivez votre API

​Spécifiez l’URL de base de votre API

​Configurer les téléversements de fichiers

​Spécifier l’authentification

​Définir des valeurs par défaut pour les schémas de sécurité

​Transformez votre spécification avec des overlays

​Créer un document d’overlay

​Référencer les overlays dans votre docs.json

​Découverte automatique des overlays

​Renommer un chemin

​Permettez aux visiteurs de télécharger votre spécification

​Personnalisez les pages de vos endpoints

​Métadonnées

​Contenu

​href

​Réduire les champs du playground

​Pastilles de paramètre

​Noms d’affichage des groupes

​Remplir automatiquement les pages d’API

​Sections d’API dédiées

​Points de terminaison sélectifs

​Définir une spécification OpenAPI par défaut

​Héritage de la spécification OpenAPI

​Points de terminaison individuels

​Créer des pages MDX à partir de votre spécification OpenAPI

​Documenter les endpoints

​Générer automatiquement des pages d’endpoint

​Documenter les modèles de données

​Webhooks

​Callbacks

Ajouter un fichier de spécification OpenAPI

Décrivez votre API

Spécifiez l’URL de base de votre API

Configurer les téléversements de fichiers

Spécifier l’authentification

Définir des valeurs par défaut pour les schémas de sécurité

Transformez votre spécification avec des overlays

Créer un document d’overlay

Référencer les overlays dans votre docs.json

Découverte automatique des overlays

Renommer un chemin

Permettez aux visiteurs de télécharger votre spécification

Personnalisez les pages de vos endpoints

Métadonnées

Contenu

href

Réduire les champs du playground

Pastilles de paramètre

Noms d’affichage des groupes

Remplir automatiquement les pages d’API

Sections d’API dédiées

Points de terminaison sélectifs

Définir une spécification OpenAPI par défaut

Héritage de la spécification OpenAPI

Points de terminaison individuels

Créer des pages MDX à partir de votre spécification OpenAPI

Documenter les endpoints

Générer automatiquement des pages d’endpoint

Documenter les modèles de données

Webhooks

Callbacks