Playground

Permettez aux utilisateurs d’interagir avec votre API

​

Aperçu

Le Terrain de jeu API est un environnement interactif qui permet aux utilisateurs de tester et d’explorer vos points de terminaison d’API. Les développeurs peuvent composer des requêtes API, les envoyer et consulter les réponses sans quitter votre documentation.

Le terrain de jeu 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 y est automatiquement reflétée. 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 Terrain de jeu API à partir d’une spécification OpenAPI. Consultez OpenAPI Setup pour plus d’informations sur la création de votre document OpenAPI.

​

Pour commencer

1. Ajoutez votre fichier de spécification OpenAPI.

   Vérifiez que votre fichier de spécification OpenAPI est valide avec le Swagger Editor ou le 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 à 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 organise sous le groupe « 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 des endpoints supplémentaires au tableau pages.

   "navigation": {
     "groups": [
         {
           "group": "API reference",
           "openapi": "openapi.json",
           "pages": [
             "GET /users",
             "POST /users"
           ]
         }
     ]
   }
   

​

Personnaliser votre terrain de jeu

Vous pouvez personnaliser votre Terrain de jeu API en définissant les propriétés suivantes dans votre docs.json.

playground · object

Configurations du Terrain de jeu API.

Masquer playground

display · "interactive" | "simple" | "none"

Le mode d’affichage du Terrain de jeu API.

• "interactive" : Affiche le terrain de jeu interactif.
• "simple" : Affiche un endpoint copiable sans terrain de jeu.
• "none" : N’affiche rien.

Par défaut : interactive.

proxy · boolean

Indique s’il faut faire transiter les requêtes API par un serveur proxy. Par défaut : true.

examples · object

Configurations pour les exemples API générés automatiquement.

Masquer examples

languages · array of string

Langages d’exemple pour les Snippets API générés automatiquement.

Les langages s’affichent dans l’ordre indiqué.

defaults · "required" | "all"

Indique s’il faut afficher les paramètres optionnels dans les exemples API. Par défaut : all.

​

Exemple de configuration

{
 "api": {
   "playground": {
     "display": "interactif"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "obligatoire"
   }
 }
}

Cet exemple configure le Terrain de jeu API pour qu’il soit interactif, avec des Snippets de code d’exemple pour cURL, Python et JavaScript. Seuls les paramètres requis sont affichés dans les Snippets.

​

Pages d’endpoints personnalisées

Lorsque vous avez besoin de plus 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 page
• Ajouter du contenu supplémentaire, comme des exemples
• Contrôler le comportement du playground par page

L’extension x-mint est recommandée afin que l’ensemble de votre documentation d’API soit généré automatiquement à partir de votre spécification OpenAPI et maintenu dans un fichier unique.

Les pages MDX individuelles sont recommandées pour les petites API ou lorsque vous souhaitez expérimenter des modifications au cas par cas.

Pour en savoir plus, consultez l’extension x-mint et la 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.