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.

​
Bien démarrer

1

Ajoutez votre fichier de spécification OpenAPI.

Vérifiez la validité de votre spécification OpenAPI avec le Swagger Editor ou la Interface en ligne de commande (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 à tout élément de navigation pour remplir automatiquement votre documentation avec des pages 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 regroupe sous « API reference » dans votre navigation.
"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "openapi.json"
    }
  ]
}
Pour ne générer des pages que pour certains endpoints, listez-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’endpoint, ajoutez les endpoints supplémentaires au tableau pages.
"navigation": {
  "groups": [
      {
        "group": "API reference",
        "openapi": "openapi.json",
        "pages": [
          "GET /users",
          "POST /users"
        ]
      }
  ]
}

​
Personnalisation de 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 des exemples d’API générés automatiquement.

​
Exemple de configuration

{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required",
     "prefill": true
   }
 }
}
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 obligatoires sont affichés dans les extraits, et le bac à sable préremplit le corps de la requête avec des valeurs d’exemple.

​
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