Playground de l'API
Testez les endpoints API directement depuis votre documentation avec le playground interactif. Renseignez les paramètres, consultez des exemples de code en direct et envoyez de vraies requêtes.
Le playground API ajoute un bouton interactif « Try it » sur vos pages d'endpoint API. Les développeurs peuvent renseigner les paramètres, observer les exemples de code se mettre à jour en temps réel et envoyer de vraies requêtes HTTP, sans jamais quitter votre documentation.
Les captures d'écran montrent l'interface en anglais.
Démarrage rapide
Le playground est activé par défaut. Toute page disposant d'un champ frontmatter openapi: ou api: obtient automatiquement un bouton « Try it ». Le CORS est géré automatiquement.
Aucune configuration dans docs.json n'est nécessaire. Ajoutez un champ openapi: ou api: dans le frontmatter de votre page et le playground apparaît.
Modes d'affichage
Le champ display contrôle ce que le playground peut faire :
| Mode | Bouton « Try it » | Remplir les paramètres | Code en direct | Envoyer la requête |
|---|---|---|---|---|
"interactive" (défaut) | ✓ | ✓ | ✓ | ✓ |
"simple" | ✓ | ✓ | ✓ | ✗ |
"none" | ✗ | ✗ | ✗ | ✗ |
Expérience complète du playground. Les développeurs renseignent 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, les délais et les corps formatés.
{
"api": {
"playground": {
"display": "interactive"
}
}
}Authentification
Si votre API requiert 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 uniquement en mémoire pour la session en cours. Ils ne sont jamais enregistrés dans localStorage ni persistés entre les visites.
Pré-remplissage des valeurs d'exemple
Lorsque votre spec 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.
Remplacement par page
Remplacez le mode d'affichage global sur des pages individuelles en utilisant le champ frontmatter playground :
---
title: Create Ticket
openapi: POST /tickets
playground: interactive
---Utile lorsque vous souhaitez désactiver le playground globalement mais l'activer sur des endpoints de démonstration spécifiques, ou inversement.
| 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 en superposition 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 signalés. L'URL de base est extraite du champ servers de votre spec 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 Envoyer (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 renvoyer quelqu'un directement vers la vue playground d'un endpoint.
Raccourcis clavier
| Raccourci | Action |
|---|---|
Ctrl/Cmd + Enter | Envoyer la requête |
Escape | Fermer le playground |
Fonctionne 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 spec OpenAPI. Aucune configuration supplémentaire n'est nécessaire.
---
openapi: POST /tickets
---Développement local
Lors de l'exécution de 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é. Visitez la page Exemple OpenAPI et cliquez sur « Try it » pour le voir en action avec l'API de démonstration.