Paramètres d'API

Configurez les spécifications OpenAPI et AsyncAPI, le playground API, les exemples de code SDK et les paramètres d’authentification dans docs.json.

Utilisez le champ api dans docs.json pour configurer les spécifications d’API qui génèrent les pages d’API, le playground d’API interactif pour tester les endpoints, et comment générer et afficher les exemples de code.

Paramètres

`api`

Type : object

Définissez tous les paramètres liés à l’API sous la clé api.

api.openapistring or array or object

Fichiers de spécification OpenAPI pour générer des pages de référence d’API. Accepte un chemin ou une URL unique, un tableau de chemins et d’URL, ou un objet spécifiant une source et un répertoire.

Show api.openapi object

sourcestring

URL ou chemin vers votre fichier de spécification OpenAPI. Longueur minimale : 1.

directorystring

Répertoire dans lequel rechercher les fichiers OpenAPI. N’incluez pas de barre oblique initiale.

"openapi": "openapi.json"

api.asyncapistring or array or object

Fichiers de spécification AsyncAPI pour générer des pages de référence d’API événementielles. Accepte un chemin ou une URL unique, un tableau de chemins et d’URL, ou un objet spécifiant une source et un répertoire.

Show api.asyncapi object

sourcestring

URL ou chemin vers votre fichier de spécification AsyncAPI. Longueur minimale : 1.

directorystring

Répertoire dans lequel rechercher les fichiers AsyncAPI. N’incluez pas de barre oblique initiale.

"asyncapi": "asyncapi.json"

api.playgroundobject

Paramètres du playground d’API interactif.

Show api.playground

display"interactive" | "simple" | "none" | "auth"

Le mode d’affichage du playground. Valeur par défaut : interactive.

interactive — Playground interactif complet avec constructeur de requêtes
simple — Vue simplifiée sans le constructeur de requêtes
none — Masquer complètement le playground
auth — Afficher le playground uniquement aux utilisateurs authentifiés

proxyboolean

Indique s’il faut router les requêtes d’API via un serveur proxy. Valeur par défaut : true.

credentialsboolean

Indique s’il faut inclure les cookies et les en-têtes d’authentification pour les requêtes cross-origin lorsque proxy est false. Valeur par défaut : false. N’a aucun effet lorsque proxy est true.

api.paramsobject

Paramètres d’affichage des paramètres d’API.

Show api.params

expanded"all" | "closed"

Indique s’il faut développer tous les paramètres par défaut. Valeur par défaut : closed.

postarray of string

Clés de champs de la spécification OpenAPI à faire apparaître sous forme de pastilles post à côté du nom de chaque paramètre dans les pages de référence d’API et dans le playground. Pour chaque clé que vous listez, Mintlify lit la valeur depuis le schéma et l’affiche sous forme de pastille :

Les valeurs de chaîne sont affichées telles quelles.
true affiche le nom de la clé comme libellé de la pastille. false, null et les chaînes vides n’affichent rien.
Les valeurs numériques sont affichées sous forme de chaîne.
Les tableaux de chaînes ou de nombres affichent une pastille par élément.
Les objets et les autres valeurs sont ignorés.

Utilisez ceci pour exposer des champs OpenAPI personnalisés — tels que x-internal, nullable ou des extensions de fournisseur — sous forme d’annotations visuelles sur chaque paramètre, sans configuration propriété par propriété.

api.url"full"

Mode d’affichage de l’URL de base dans l’en-tête de l’endpoint. Définissez sur full pour toujours afficher l’URL de base complète sur chaque page d’endpoint. Par défaut, l’URL de base n’est affichée que lorsqu’il y a plusieurs URL de base parmi lesquelles choisir.

api.examplesobject

Paramètres pour les exemples de code d’API générés automatiquement.

Show api.examples

languagesarray of string

Langages pour les extraits de code générés automatiquement. Voir langages pris en charge pour la liste complète des langages et alias disponibles.

defaults"required" | "all"

Indique s’il faut inclure les paramètres facultatifs dans les exemples générés. Valeur par défaut : all.

prefillboolean

Indique s’il faut préremplir le playground avec les valeurs d’exemple de votre spécification OpenAPI. Valeur par défaut : false.

autogenerateboolean

Indique s’il faut générer des exemples de code pour les endpoints à partir de votre spécification d’API. Valeur par défaut : true. Lorsque défini sur false, seuls les exemples de code écrits manuellement (à partir de x-codeSamples dans OpenAPI ou des composants <RequestExample> dans MDX) apparaissent dans le playground.

api.mdxobject

Paramètres pour les pages d’API construites à partir de fichiers MDX plutôt que de spécifications OpenAPI.

Show api.mdx

authobject

Configuration d’authentification pour les requêtes d’API basées sur MDX.

Show auth

method"bearer" | "basic" | "key" | "cobo"

Méthode d’authentification pour les requêtes d’API.

namestring

Nom du paramètre d’authentification pour les requêtes d’API.

serverstring or array

URL de base ajoutée en préfixe aux chemins relatifs dans les champs frontmatter api au niveau de la page. Non utilisée lorsque le frontmatter contient une URL complète.

Exemple

docs.json

{
  "api": {
    "openapi": ["openapi/v1.json", "openapi/v2.json"],
    "playground": {
      "display": "interactive"
    },
    "params": {
      "expanded": "all",
      "post": ["nullable", "x-internal"]
    },
    "url": "full",
    "examples": {
      "languages": ["curl", "python", "javascript", "go"],
      "defaults": "required",
      "prefill": true,
      "autogenerate": true
    }
  }
}

Paramètres d'API

Paramètres

api

Exemple

On this page

`api`