Passer au contenu principal

​
Aperçu

Le bac à sable d’API est un environnement interactif qui permet aux utilisateurs de tester et d’explorer les points de terminaison de votre API. Les développeurs peuvent composer des requêtes API, les envoyer et consulter les réponses sans quitter votre documentation.
Bac à sable d’API pour le point de terminaison déclenchant une mise à jour.
Le bac à sable est généré automatiquement à partir de votre spécification OpenAPI ou de votre schéma AsyncAPI, de sorte que toute mise à jour de votre API est automatiquement répercutée dans le bac à sable. Vous pouvez également créer manuellement des pages de référence de l’API après avoir défini une URL de base et une méthode d’authentification dans votre docs.json. Nous recommandons de générer votre bac à sable d’API à partir d’une spécification OpenAPI. Consultez Configuration OpenAPI pour plus d’informations sur la création de votre document OpenAPI.

​
Pour commencer

1

Ajoutez votre fichier de spécification OpenAPI.

Vérifiez la validité de votre spécification OpenAPI avec le Swagger Editor ou la CLI Mint.
/your-project
  |- docs.json
  |- openapi.json
2

Configurez `docs.json`.

Mettez à jour votre docs.json pour référencer votre spécification OpenAPI. Ajoutez une propriété openapi à n’importe quel élément de navigation pour renseigner automatiquement votre documentation avec une page pour chaque endpoint défini dans votre document OpenAPI.Cet exemple génère une page pour chaque endpoint défini dans openapi.json et les organise sous le groupe « API reference » dans votre navigation.
"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "openapi.json"
    }
  ]
}
Pour générer des pages uniquement pour certains endpoints, énumérez-les dans la propriété pages de l’élément de navigation.Cet exemple génère des pages uniquement pour les endpoints GET /users et POST /users. Pour générer d’autres pages d’endpoints, ajoutez des endpoints supplémentaires au tableau pages.
"navigation": {
  "groups": [
      {
        "group": "API reference",
        "openapi": "openapi.json",
        "pages": [
          "GET /users",
          "POST /users"
        ]
      }
  ]
}

​
Personnaliser votre bac à sable

Vous pouvez personnaliser votre bac à sable d’API en définissant les propriétés suivantes dans votre docs.json.
​
playground
object
Paramètres de configuration du bac à sable d’API.
​
examples
object
Paramètres de configuration pour les exemples d’API générés automatiquement.

​
Exemple de configuration

{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required"
   }
 }
}
Cet exemple configure le bac à sable d’API pour qu’il soit interactif, avec des extraits de code pour cURL, Python et JavaScript. Seuls les paramètres requis sont affichés dans les extraits de code.

​
Pages d’endpoint personnalisées

Lorsque vous avez besoin d’un contrôle plus fin sur votre documentation API, utilisez l’extension x-mint dans votre spécification OpenAPI ou créez des pages MDX individuelles pour vos endpoints. Ces deux options vous permettent de :
  • Personnaliser les metadata de la page
  • Ajouter du contenu supplémentaire, comme des exemples
  • Contrôler le comportement du playground par page
Nous recommandons l’extension x-mint afin que l’ensemble de votre documentation API soit automatiquement généré à partir de votre spécification OpenAPI et maintenu dans un seul fichier. Les pages MDX individuelles sont recommandées pour les petites API ou lorsque vous souhaitez expérimenter des modifications page par page. Pour plus d’informations, voir x-mint extension et MDX Setup.

​
Pour aller plus loin

  • Configuration d’AsyncAPI pour en savoir plus sur la création de votre schéma AsyncAPI afin de générer des pages de référence WebSocket.
⌘I