API-Playground

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.

Schnellstart

Der Playground ist standardmäßig aktiviert, ohne docs.json-Konfiguration. Jede Seite mit einem Frontmatter-Feld openapi: oder api: erhält eine Schaltfläche „Try it“. CORS erfordert keine Einrichtung.

Anzeigemodi

Das Feld display steuert, was der Playground kann:

Modus	Schaltfläche „Try it“	Parameter ausfüllen	Live-Code	Anfrage senden
`"interactive"` (Standard)	✓	✓	✓	✓
`"simple"`	✓	✓	✓	✗
`"none"`	✗	✗	✗	✗

Vollständiges Playground-Erlebnis. Entwickler füllen Parameter aus, sehen Codebeispiele live aktualisiert und senden echte HTTP-Anfragen. Antworten werden inline mit Statuscodes, Dauer und formatierten Inhalten angezeigt.

docs.json

{
  "api": {
    "playground": {
      "display": "interactive"
    }
  }
}

Authentifizierung

Der Playground zeigt oben im Parameterformular ein Authentifizierungsfeld an, wenn Ihre API eine Authentifizierung erfordert (konfiguriert über api.mdx.auth.method in docs.json). Entwickler geben ihren API-Schlüssel oder Token im Modal ein.

Zugangsdaten werden nur für die aktuelle Sitzung im Speicher gehalten. Sie werden nie in localStorage gespeichert oder zwischen Besuchen beibehalten.

Beispielwerte vorausfüllen

Der Playground kann die Werte example von Parametern und Anfragekörpern in Ihrer OpenAPI-Spezifikation vorausfüllen:

docs.json

{
  "api": {
    "examples": {
      "prefill": true
    }
  }
}

Entwickler starten mit realistischen Werten statt mit leeren Feldern.

Seitenbezogene Überschreibung

Überschreiben Sie den globalen Anzeigemodus auf einzelnen Seiten mit dem Frontmatter-Feld playground:

---
title: Create Ticket
openapi: POST /tickets
playground: interactive
---

Verwenden Sie dies, um den Playground global auszuschalten, aber für bestimmte Demo-Endpunkte einzuschalten – oder umgekehrt.

Frontmatter	Verhalten
`playground: interactive`	Vollständiger Playground auf dieser Seite
`playground: simple`	Nur-Code-Playground auf dieser Seite
`playground: none`	Kein Playground auf dieser Seite

Funktionsweise

Auf „Try it“ klicken

Der Playground öffnet sich als Vollbild-Modal-Overlay. Ihre Dokumentationsseite bleibt darunter unverändert.

Parameter ausfüllen

Pfad-, Abfrage-, Header- und Body-Parameter werden als Formularfelder angezeigt. Pflichtfelder sind markiert. Die Basis-URL wird aus dem Feld servers Ihrer OpenAPI-Spezifikation übernommen.

Code aktualisieren beobachten

Codebeispiele werden beim Tippen in jeder konfigurierten Sprache neu generiert. Jedes Beispiel lässt sich mit einem Klick kopieren.

Anfrage senden

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.

API playground showing a 201 Created response with JSON body after sending a request

Während der Playground geöffnet ist, erhält die URL ?playground=open. Teilen Sie diese URL, um direkt zur Playground-Ansicht eines Endpunkts zu verlinken.

Mehrere Server

Neben der Endpunkt-URL erscheint eine Serverauswahl, wenn die Spezifikation eines Endpunkts mehr als einen Eintrag unter servers auflistet (zum Beispiel Produktion und Sandbox). Die Auswahl des Lesers legt die Basis-URL fest, die Schaltfläche zum Kopieren der URL, die Codebeispiele auf der Seite und die Anfrage, die der Playground sendet.

Endpunkte mit einem einzigen Server zeigen keine Auswahl und erhöhen die Seitengröße nicht.

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 das Frontmatter-Format openapi: oder api: verwenden:

Jamdesk übernimmt Parameter und Schemata aus Ihrer OpenAPI-Spezifikation. Keine Einrichtung nötig.

---
openapi: POST /tickets
---

Lokale Entwicklung

Der Playground funktioniert nur in der Produktion. jamdesk dev zeigt die Schaltflächen „Try it“ an. Ein Klick darauf zeigt eine kurze Benachrichtigung, anstatt das Modal zu öffnen. Stellen Sie Ihre Dokumentation bereit, um den vollen Playground zu nutzen.

Live ausprobieren

Auf dieser Website ist der Playground aktiviert. Öffnen Sie die Seite OpenAPI Example und klicken Sie auf „Try it“, um eine Anfrage an die Demo-API zu senden.

Wie geht es weiter?

OpenAPI-Beispiel

Sehen Sie einen Live-Playground auf einer automatisch generierten Endpunktseite

docs.json-Referenz

Vollständige Konfigurationsreferenz einschließlich api.playground

Request/Response-Beispiele

Handgeschriebene API-Endpunktseiten mit MDX-Komponenten

Codebeispiele

Konfigurieren Sie, welche Sprachen in Codebeispielen erscheinen

Die Screenshots zeigen die Benutzeroberfläche auf Englisch.