API-Playground
Testen Sie API-Endpunkte direkt in Ihrer Dokumentation mit dem interaktiven Playground: Parameter ausfüllen, Live-Code sehen und echte Anfragen senden.
Der API-Playground fügt Ihren API-Endpunktseiten eine interaktive Schaltfläche „Try it“ hinzu. Entwickler füllen Parameter aus, sehen Codebeispiele in Echtzeit aktualisiert und senden echte HTTP-Anfragen direkt von der Dokumentationsseite.
Die Screenshots zeigen die Benutzeroberfläche auf Englisch.
Schnellstart
Der Playground ist standardmäßig aktiviert. Jede Seite mit einem openapi:- oder api:-Frontmatter-Feld erhält automatisch eine „Try it“-Schaltfläche. CORS wird automatisch verarbeitet.
Keine docs.json-Konfiguration ist erforderlich. Fügen Sie dem Frontmatter Ihrer Seite ein openapi:- oder api:-Feld hinzu, damit der Playground angezeigt wird.
Anzeigemodi
Das Feld display steuert, welche Aktionen der Playground ausführen kann:
| Modus | „Try it“-Schaltfläche | Parameter ausfüllen | Live-Code | Anfrage senden |
|---|---|---|---|---|
"interactive" (Standard) | ✓ | ✓ | ✓ | ✓ |
"simple" | ✓ | ✓ | ✓ | ✗ |
"none" | ✗ | ✗ | ✗ | ✗ |
Vollständiger Playground. Entwickler füllen Parameter aus, sehen Codebeispiele live aktualisiert und senden echte HTTP-Anfragen. Antworten werden inline mit Statuscodes, Zeitangaben und formatierten Inhalten angezeigt.
{
"api": {
"playground": {
"display": "interactive"
}
}
}Authentifizierung
Wenn Ihre API eine Authentifizierung erfordert (konfiguriert über api.mdx.auth.method in docs.json), zeigt der Playground oben im Parameterformular ein Authentifizierungsfeld an. Entwickler geben ihren API-Schlüssel oder ihr Token direkt im Modal ein.
Anmeldedaten werden nur für die aktuelle Sitzung im Arbeitsspeicher gehalten. Sie werden niemals in localStorage gespeichert oder zwischen Besuchen beibehalten.
Beispielwerte vorausfüllen
Wenn Ihre OpenAPI-Spezifikation example-Werte für Parameter und Request-Bodies enthält, kann der Playground diese vorausfüllen:
{
"api": {
"examples": {
"prefill": true
}
}
}Das spart Entwicklern Zeit, da realistische Werte angezeigt werden, die sie ändern können, anstatt mit leeren Feldern zu beginnen.
Seitenbezogene Überschreibung
Überschreiben Sie den globalen Anzeigemodus auf einzelnen Seiten mit dem playground-Frontmatter-Feld:
---
title: Create Ticket
openapi: POST /tickets
playground: interactive
---Nützlich, wenn der Playground global deaktiviert, aber für bestimmte Demo-Endpunkte aktiviert werden soll – oder umgekehrt.
| Frontmatter | Verhalten |
|---|---|
playground: interactive | Vollständiger Playground auf dieser Seite |
playground: simple | Playground nur für Code auf dieser Seite |
playground: none | Kein Playground auf dieser Seite |
Funktionsweise
Der Playground wird als bildschirmfüllendes Modal-Overlay geöffnet. Ihre Dokumentationsseite bleibt darunter unverändert erhalten.
Pfad-, Query-, Header- und Body-Parameter werden als Formularfelder angezeigt. Pflichtfelder sind markiert. Die Basis-URL wird aus dem servers-Feld Ihrer OpenAPI-Spezifikation übernommen.
Während der Eingabe werden Codebeispiele in allen konfigurierten Programmiersprachen in Echtzeit neu generiert. Kopieren Sie jedes Beispiel mit einem Klick.
Klicken Sie im interaktiven Modus auf Send (oder drücken Sie Ctrl/Cmd+Enter), um die Anfrage auszuführen. Die Antwort wird darunter mit Statuscode, Dauer und formatiertem Inhalt angezeigt.
Wenn der Playground geöffnet ist, wird die URL um ?playground=open ergänzt. Teilen Sie diese URL, um direkt zur Playground-Ansicht eines Endpunkts zu verlinken.
Mehrere Server
Wenn die Spezifikation eines Endpunkts mehr als einen Eintrag unter servers aufführt – beispielsweise einen für die Produktion und einen für die Sandbox –, wird neben der Endpunkt-URL eine Serverauswahl angezeigt. Die Auswahl bestimmt die Basis-URL, die Schaltfläche zum Kopieren der URL, die Codebeispiele auf der Seite und die Anfrage, die der Playground tatsächlich sendet. So kopiert niemand einen Produktions-curl, während er die Sandbox-Dokumentation liest.
Endpunkte mit nur einem Server bleiben unverändert: keine Auswahl und kein zusätzliches Seitengewicht.
Tastaturkürzel
| Tastenkürzel | Aktion |
|---|---|
Ctrl/Cmd + Enter | Anfrage senden |
Escape | Playground schließen |
Funktioniert mit beiden API-Seitentypen
Der Playground funktioniert auf Seiten, die entweder das openapi:- oder das api:-Frontmatter-Format verwenden:
Parameter und Schemas werden automatisch aus Ihrer OpenAPI-Spezifikation übernommen. Keine zusätzliche Einrichtung erforderlich.
---
openapi: POST /tickets
---Lokale Entwicklung
Wenn Sie jamdesk dev ausführen, sind die „Try it“-Schaltflächen sichtbar, der Playground selbst ist jedoch nur für die Produktion verfügbar. Wenn Sie in der lokalen Entwicklung auf „Try it“ klicken, wird statt des Modals eine kurze Benachrichtigung angezeigt. Stellen Sie Ihre Dokumentation bereit, um den vollständigen Playground zu verwenden.
Live ausprobieren
Auf dieser Dokumentationsseite ist der Playground aktiviert. Besuchen Sie die Seite OpenAPI-Beispiel und klicken Sie auf „Try it“, um ihn mit der Demo-API auszuprobieren.