Playground

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

Voir Déclencher une mise à jour pour un exemple du playground API en action.

Le playground génère des pages interactives pour vos endpoints à partir de votre spécification OpenAPI ou de votre schéma AsyncAPI. Si vous modifiez votre API, il met automatiquement à jour les pages concernées.

Nous recommandons de générer votre playground API à partir d’une spécification OpenAPI. Cependant, vous pouvez 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.

/your-project
  |- docs.json
  |- openapi.json

"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "openapi.json"
    }
  ]
}

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

Personnalisez votre bac à sable d’API en définissant les propriétés suivantes dans votre docs.json.

Cet exemple configure l’aire de test de l’API pour être interactive, avec des extraits de code pour cURL, Python et JavaScript. Il n’affiche que les paramètres requis dans les extraits de code, et l’aire de test préremplit le corps de la requête avec des valeurs d’exemple.

{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required",
     "prefill": true
   }
 }
}

Utilisez le mode d’affichage auth pour afficher le playground interactif uniquement aux utilisateurs authentifiés. C’est utile lorsque vous voulez rendre la documentation de votre API publique tout en restreignant l’accès au playground aux utilisateurs connectés.

Lorsque display est défini sur auth :

• Les utilisateurs authentifiés voient le playground interactif.
• Les utilisateurs non authentifiés ne voient aucun playground (équivalent à none).

Vous pouvez également combiner auth avec la propriété groups dans le frontmatter de la page pour restreindre l’accès au playground à des groupes d’utilisateurs spécifiques.

---
title: "Créer un utilisateur"
openapi: POST /users
playground: auth
groups: ["admin", "developer"]
public: true
---

Dans cet exemple :

• La page est publique (tout le monde peut consulter la documentation).
• Seuls les utilisateurs authentifiés appartenant aux groupes admin ou developer voient l’espace de test interactif.
• Les utilisateurs qui ne sont pas dans ces groupes ne voient aucun espace de test.

Si la page ne comporte pas de propriété groups, tous les utilisateurs authentifiés voient l’espace de test interactif.

Lorsque vous avez besoin d’un contrôle plus fin sur votre documentation d’API, utilisez l’extension x-mint dans votre spécification OpenAPI ou créez des pages MDX individuelles pour vos endpoints.

Les deux options vous permettent de :

• Personnaliser la metadata de la page
• Ajouter du contenu supplémentaire, comme des exemples
• Contrôler le comportement du playground pour chaque page

Nous recommandons l’extension x-mint afin que toute votre documentation d’API soit automatiquement générée à partir de votre spécification OpenAPI et maintenue dans un seul fichier.

Nous recommandons les pages MDX individuelles pour les petites API ou lorsque vous souhaitez expérimenter des modifications page par page.

Le playground rend automatiquement les réponses en fonction de l’en-tête Content-Type renvoyé par votre API.

• Images : Rendues en ligne (image/*).
• Audio : Rendu avec un lecteur audio intégré (audio/*).
• Vidéo : Rendue avec un lecteur vidéo intégré (video/*). Toute réponse avec un type de contenu video/*, tel que video/mp4 ou video/webm, s’affiche sous forme de vidéo lisible directement dans le playground.
• Toutes les autres réponses : Affichées dans un bloc de code.

Chaque paramètre dans le playground API dispose d’un lien d’ancrage cliquable. Survolez le nom d’un paramètre pour révéler l’icône de lien, puis cliquez pour copier une URL directe vers ce paramètre.

Utilisez les liens d’ancrage des paramètres pour :

• Partager des liens vers des paramètres spécifiques dans des conversations de support ou de la documentation
• Naviguer directement vers un paramètre depuis une autre page ou une ressource externe
• Ajouter aux favoris les paramètres fréquemment consultés

Le format de l’URL est votre-url-docs/chemin-endpoint#nom-du-parametre. Pour les paramètres imbriqués, l’ancrage inclut le chemin du parent.

• Configuration d’OpenAPI pour en savoir plus sur la création de votre document OpenAPI.
• Extension x-mint pour en savoir plus sur la personnalisation de vos pages de points de terminaison.
• Configuration de MDX pour en savoir plus sur la création manuelle de pages de référence API individuelles.
• 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.