API Playground
Testez les endpoints API de vos docs avec le playground interactif : remplissez les paramètres, voyez des exemples de code, envoyez de vraies requêtes.
Le playground API ajoute un bouton interactif "Try it" sur les pages de vos endpoints API. Les développeurs remplissent les paramètres, voient les exemples de code se mettre à jour en temps réel, et envoient de vraies requêtes HTTP depuis la page de documentation.
Les captures d'écran montrent l'interface en anglais.
Démarrage rapide
Le playground est activé par défaut. Chaque page comportant un champ frontmatter openapi: ou api: reçoit automatiquement un bouton "Try it". CORS est géré automatiquement.
Aucune configuration docs.json n'est nécessaire. Ajoutez un champ openapi: ou api: au frontmatter de votre page et le playground apparaît.
Modes d'affichage
Le champ display détermine ce que le playground peut faire :
| Mode | Bouton "Try it" | Remplir les paramètres | Code en direct | Envoyer la requête |
|---|---|---|---|---|
"interactive" (par défaut) | ✓ | ✓ | ✓ | ✓ |
"simple" | ✓ | ✓ | ✓ | ✗ |
"none" | ✗ | ✗ | ✗ | ✗ |
Expérience complète du playground. Les développeurs remplissent les paramètres, voient les exemples de code se mettre à jour en direct, et envoient de vraies requêtes HTTP. Les réponses s'affichent en ligne avec les codes de statut, la durée et le corps formaté.
{
"api": {
"playground": {
"display": "interactive"
}
}
}Authentification
Si votre API nécessite une authentification (configurée via api.mdx.auth.method dans docs.json), le playground affiche un champ de saisie d'authentification en haut du formulaire de paramètres. Les développeurs saisissent leur clé API ou leur token directement dans la fenêtre modale.
Les identifiants sont conservés en mémoire uniquement pour la session en cours. Ils ne sont jamais enregistrés dans localStorage ni conservés entre les visites.
Pré-remplissage des valeurs d'exemple
Lorsque votre spécification OpenAPI inclut des valeurs example sur les paramètres et les corps de requête, le playground peut les pré-remplir :
{
"api": {
"examples": {
"prefill": true
}
}
}Cela fait gagner du temps aux développeurs en affichant des valeurs réalistes qu'ils peuvent modifier plutôt que de partir de champs vides.
Redéfinition par page
Redéfinissez le mode d'affichage global sur des pages individuelles à l'aide du champ frontmatter playground :
---
title: Create Ticket
openapi: POST /tickets
playground: interactive
---Utile lorsque vous voulez désactiver le playground globalement mais l'activer sur des endpoints de démonstration spécifiques, ou l'inverse.
| Frontmatter | Comportement |
|---|---|
playground: interactive | playground complet sur cette page |
playground: simple | playground code uniquement sur cette page |
playground: none | Aucun playground sur cette page |
Fonctionnement
Le playground s'ouvre dans une fenêtre modale en plein écran. Votre page de documentation reste intacte en dessous.
Les paramètres de chemin, de requête, d'en-tête et de corps sont affichés sous forme de champs de formulaire. Les champs obligatoires sont marqués. L'URL de base est extraite du champ servers de votre spécification OpenAPI.
Au fur et à mesure que vous tapez, les exemples de code se régénèrent en temps réel dans tous les langages configurés. Copiez n'importe quel exemple en un clic.
En mode interactif, cliquez sur Send (ou appuyez sur Ctrl/Cmd+Enter) pour exécuter la requête. La réponse s'affiche en dessous avec le code de statut, la durée et le corps formaté.
Lorsque le playground est ouvert, l'URL se met à jour pour inclure ?playground=open. Partagez cette URL pour envoyer quelqu'un directement vers la vue playground d'un endpoint.
Serveurs multiples
Lorsque la spécification d'un endpoint répertorie plusieurs entrées sous servers — production et sandbox, par exemple — un sélecteur de serveur apparaît à côté de l'URL de l'endpoint. Ce que le lecteur choisit détermine l'URL de base, le bouton de copie d'URL, les exemples de code sur la page, ainsi que la requête réellement envoyée par le playground, afin que personne ne copie une commande curl de production en lisant la documentation du sandbox.
Les endpoints avec un seul serveur restent inchangés : pas de sélecteur, pas de poids supplémentaire sur la page.
Raccourcis clavier
| Raccourci | Action |
|---|---|
Ctrl/Cmd + Enter | Envoyer la requête |
Escape | Fermer le playground |
Compatible avec les deux types de pages API
Le playground fonctionne sur les pages utilisant le format frontmatter openapi: ou api: :
Les paramètres et les schémas sont extraits automatiquement de votre spécification OpenAPI. Aucune configuration supplémentaire n'est nécessaire.
---
openapi: POST /tickets
---Développement local
Lorsque vous exécutez jamdesk dev, les boutons "Try it" sont visibles, mais le playground lui-même est une fonctionnalité réservée à la production. Cliquer sur "Try it" en développement local affiche une brève notification au lieu d'ouvrir la fenêtre modale. Déployez votre documentation pour utiliser le playground complet.
Essayez-le en direct
Ce site de documentation a le playground activé. Consultez la page Exemple OpenAPI et cliquez sur "Try it" pour le voir en action avec l'API de démonstration.