​
Vue d’ensemble

Le bac à sable API est un environnement interactif qui permet aux utilisateurs de tester et d’explorer vos points de terminaison API. Les développeurs peuvent composer des requêtes API, les soumettre et consulter les réponses sans quitter votre documentation.
Bac à sable API pour l’endpoint de déclenchement d’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 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 API à partir d’une spécification OpenAPI. Consultez Configuration OpenAPI pour en savoir plus sur la création de votre document OpenAPI.

​
Bien démarrer

1

Ajoutez votre fichier de spécification OpenAPI.

Assurez-vous que votre fichier de spécification OpenAPI est valide à l’aide du Swagger Editor ou de la Mint CLI.
/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 remplir 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-les 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 API en définissant les propriétés suivantes dans votre docs.json.
​
playground
object
Configuration du bac à sable API.
​
examples
object
Configuration des 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 API pour être interactif et inclure des extraits de code pour cURL, Python et JavaScript. Seuls les paramètres requis sont affichés dans ces extraits.

​
Pages d’endpoint personnalisées

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

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