​
Übersicht

Die API-Spielwiese ist eine interaktive Umgebung, in der Benutzer Ihre API-Endpunkte testen und erkunden können. Entwickler können API-Anfragen erstellen, senden und Antworten ansehen, ohne Ihre Dokumentation zu verlassen.
API-Spielwiese für den Endpunkt zum Auslösen eines Updates.
Die Spielwiese wird automatisch aus Ihrer OpenAPI-Spezifikation oder Ihrem AsyncAPI-Schema generiert, sodass alle Aktualisierungen Ihrer API automatisch in der Spielwiese reflektiert werden. Sie können auch manuell API-Referenzseiten erstellen, nachdem Sie in Ihrer docs.json eine Basis-URL und eine Authentifizierungsmethode definiert haben. Wir empfehlen, Ihre API-Spielwiese auf Basis einer OpenAPI-Spezifikation zu erzeugen. Weitere Informationen zur Erstellung Ihres OpenAPI-Dokuments finden Sie unter OpenAPI Setup.

​
Erste Schritte

1

Fügen Sie Ihre OpenAPI-Spezifikationsdatei hinzu.

Vergewissern Sie sich, dass Ihre OpenAPI-Spezifikationsdatei gültig ist – zum Beispiel mit dem Swagger Editor oder der Mint CLI.
/your-project
  |- docs.json
  |- openapi.json
2

Konfigurieren Sie `docs.json`.

Aktualisieren Sie Ihre docs.json, um auf Ihre OpenAPI-Spezifikation zu verweisen. Fügen Sie einem Navigationselement die Eigenschaft openapi hinzu, damit Ihre Doku automatisch mit Seiten für jeden im OpenAPI-Dokument definierten Endpunkt befüllt wird.Dieses Beispiel erzeugt für jeden in openapi.json definierten Endpunkt eine Seite und ordnet sie in der Navigation der Gruppe „API reference“ zu.
"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "openapi.json"
    }
  ]
}
Um Seiten nur für bestimmte Endpunkte zu generieren, listen Sie diese in der Eigenschaft pages des Navigationselements auf.Dieses Beispiel erzeugt Seiten nur für die Endpunkte GET /users und POST /users. Um weitere Endpunktseiten zu generieren, fügen Sie zusätzliche Endpunkte zum Array pages hinzu.
"navigation": {
  "groups": [
      {
        "group": "API reference",
        "openapi": "openapi.json",
        "pages": [
          "GET /users",
          "POST /users"
        ]
      }
  ]
}

​
Anpassen Ihrer Spielwiese

Sie können Ihre API-Spielwiese anpassen, indem Sie die folgenden Eigenschaften in Ihrer docs.json definieren.
​
playground
object
Konfigurationen für die API-Spielwiese.
​
examples
object
Konfigurationen für die automatisch generierten API-Beispiele.

​
Beispielkonfiguration

{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required"
   }
 }
}
Dieses Beispiel macht die API-Spielwiese interaktiv und fügt Beispielcode für cURL, Python und JavaScript hinzu. In den Codebeispielen werden nur erforderliche Parameter angezeigt.

​
Benutzerdefinierte Endpunktseiten

Wenn Sie mehr Kontrolle über Ihre API-Dokumentation benötigen, verwenden Sie die x-mint-Erweiterung in Ihrer OpenAPI-Spezifikation oder erstellen Sie einzelne MDX-Seiten für Ihre Endpunkte. Beide Optionen ermöglichen Ihnen:
  • Seitenmetadaten anpassen
  • Zusätzliche Inhalte wie Beispiele hinzufügen
  • Das Verhalten der API-Spielwiese pro Seite steuern
Die x-mint-Erweiterung wird empfohlen, damit Ihre gesamte API-Dokumentation automatisch aus Ihrer OpenAPI-Spezifikation generiert und in einer Datei verwaltet wird. Einzelne MDX-Seiten werden für kleine APIs oder dann empfohlen, wenn Sie Änderungen seitenweise ausprobieren möchten. Weitere Informationen finden Sie unter x-mint-Erweiterung und MDX-Einrichtung.

​
Weiterführende Lektüre

  • AsyncAPI-Setup für weitere Informationen zum Erstellen Ihres AsyncAPI-Schemas, um WebSocket-Referenzseiten zu generieren.