Paramètres d'API

Configurez les spécifications OpenAPI et AsyncAPI, le playground interactif, les exemples de code et l’authentification dans docs.json.

Utilisez le champ api dans docs.json pour configurer les spécifications d’API disponibles pour générer des pages d’API ; le playground d’API interactif avec lequel les utilisateurs peuvent tester les endpoints d’API ; 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.openapi · string 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.

Afficher api.openapi object

source · string

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

directory · string

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

Fichier unique

"openapi": "openapi.json"

api.asyncapi · string 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.

Afficher api.asyncapi object

source · string

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

directory · string

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

Fichier unique

"asyncapi": "asyncapi.json"

api.playground · object

Paramètres du playground d’API interactif.

Afficher 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

proxy · boolean

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

api.params · object

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

Afficher api.params

expanded · "all" | "closed"

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

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.examples · object

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

Afficher api.examples

languages · array 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.

prefill · boolean

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

autogenerate · boolean

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.spec · object

Paramètres d’affichage de la spécification OpenAPI. Incluant le bouton de téléchargement sur les pages de référence d’API.

Afficher api.spec

download · boolean

Indique s’il faut afficher un bouton de téléchargement pour la spécification OpenAPI sur les pages de référence d’API. Valeur par défaut : false.

api.mdx · object

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

Afficher api.mdx

auth · object

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

Afficher auth

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

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

name · string

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

server · string 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"
    },
    "url": "full",
    "examples": {
      "languages": ["curl", "python", "javascript", "go"],
      "defaults": "required",
      "prefill": true,
      "autogenerate": true
    },
    "spec": {
      "download": true
    }
  }
}