API Playground
Testez les endpoints API directement depuis votre documentation avec le playground interactif, avec paramètres et exemples de code en temps réel.
Le playground API ajoute un bouton interactif « Try it » aux 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: obtient automatiquement un bouton « Try it ». Le 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 contrôle 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, le temps de réponse 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 directement leur clé API ou leur token dans la modale.
Les identifiants sont conservés en mémoire uniquement 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 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.
Surcharge par page
Remplacez 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 | Pas de playground sur cette page |
Fonctionnement
Le playground s'ouvre sous forme de modale 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 requis sont marqués. L'URL de base est extraite du champ servers de votre spécification OpenAPI.
Au fur et à mesure de votre saisie, 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 est mise à 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 schémas sont extraits automatiquement de votre spécification OpenAPI. Aucune configuration supplémentaire 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 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.