OpenAPI-Beispiel

POSThttps://jamdesk-docs.jamdesk.app/api/playground/demo/tickets

Create a new ticket for a customer issue or request.

Loading code example

Loading code example

Body

customer_idstringrequired

Customer identifier in Acme.

subjectstringrequired

Short summary of the issue.

priority"low" | "normal" | "high" | "urgent"

Allowed values: "low" | "normal" | "high" | "urgent"

tagsarray<string>

messagestringrequired

Detailed problem description.

Response

application/json

Ticket created

idstring

customer_idstring

subjectstring

prioritystring

status"open" | "pending" | "resolved"

Allowed values: "open" | "pending" | "resolved"

tagsarray<string>

messagestring

created_atstring<date-time>

updated_atstring<date-time>

Diese Seite zeigt einen live aus einer OpenAPI-Spezifikation generierten Endpoint. Das Anfrage-Schema, die Antwortmodelle und die Codebeispiele im rechten Bereich werden automatisch aus der Spezifikation generiert, ohne dass eine manuelle Erstellung erforderlich ist.

Dieses Beispiel verwendet die Acme Support API. Aktualisieren Sie api.openapi in Ihrer docs.json, sodass die Datei auf Ihre eigene Spezifikationsdatei verweist und echte Endpoints generiert werden.

Mehrsprachige Dokumentation? Legen Sie neben Ihrer Quellspezifikation eine Datei im Format <spec>.<lang>.<ext> ab, z. B. example-api.fr.yaml. Jamdesk rendert die übersetzte Version, wenn Benutzer die Seite unter /fr/... aufrufen. Weitere Informationen finden Sie unter OpenAPI-Spezifikationen übersetzen.

Auf dieser Seite ist der API Playground aktiviert. Klicken Sie beim obigen Endpoint auf Try it, um die API live zu testen.

Was generiert wird

Aus einer einzelnen openapi-Zeile im Frontmatter generiert Jamdesk automatisch:

Ein Endpoint-Badge mit Methode und Pfad sowie entsprechender Farbcodierung
Parameterdokumentation für Pfad-, Query-, Header- und Body-Parameter
Anfrage- und Antwortschemas einschließlich verschachtelter Objekte und Arrays
Codebeispiele in cURL, Python, JavaScript, Go, Ruby, C#, Java, Rust und PHP (konfigurierbar über api.examples.languages)
Aus der Spezifikation übernommene Authentifizierungsdetails der Sicherheits-Schemas

Alle $ref-Referenzen in Ihrer Spezifikation werden automatisch aufgelöst. Daher können Sie Schemas wie gewohnt mit components/schemas organisieren.

Beschreibungen in Ihrer Spezifikation werden als Markdown gerendert und nicht als Rohtext ausgegeben. Beschreibungen von Operationen, Parametern, Anfrageinhalten, Antworten und Schemas unterstützen alle dasselbe Fett, code, Listen, Links und GFM-Tabellen, die Sie auch in einer .mdx-Seite verwenden würden.

OpenAPI einrichten

Legen Sie Ihre OpenAPI-3.x-Spezifikation (YAML oder JSON) im Verzeichnis openapi/ ab, registrieren Sie sie in docs.json unter api.openapi und fügen Sie im Frontmatter einer beliebigen Seite openapi: /openapi/your-spec.yaml METHOD /path hinzu. Ausführliche Informationen finden Sie im OpenAPI-Einrichtungsleitfaden.

Für jede Operation eine Seite generieren

Statt für jeden Endpoint eine eigene Seite zu erstellen, können Sie einen Navigations-Tab auf die Spezifikation verweisen lassen und Jamdesk die gesamte Referenz generieren lassen:

docs.json

{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": { "source": "/openapi/api.yaml", "generate": true }
      }
    ]
  }
}

Für jede Operation wird eine Seite erstellt, und die Seitenleiste wird nach Tag gruppiert. Festgeschriebene .mdx-Dateien haben bei kollidierenden Slugs Vorrang. So können Sie die Umstellung schrittweise vornehmen. Wenn Sie einen Pfad in Ihrer Spezifikation umbenennen, wird die alte URL weitergeleitet, anstatt dass sie nicht mehr funktioniert. Weitere Informationen zu den vollständigen Regeln und aktuellen Einschränkungen finden Sie unter navigation openapi.

Verfassen Sie Ihre Spezifikation in YAML? Führen Sie sie durch den kostenlosen YAML Validator, um Einrückungs- und Syntaxfehler zu erkennen, bevor der Build sie verarbeitet.