OpenAPI-Beispiel
Sehen Sie eine live generierte OpenAPI-Endpoint-Seite und erfahren Sie, wie Jamdesk Anfragen, Antworten und Authentifizierung aus Ihrer Spezifikation rendert.
Create a new ticket for a customer issue or request.
Body
customer_idstringrequiredCustomer identifier in Acme.
subjectstringrequiredShort summary of the issue.
priority"low" | "normal" | "high" | "urgent""low" | "normal" | "high" | "urgent"tagsarray<string>messagestringrequiredDetailed problem description.
Response
Ticket created
idstringcustomer_idstringsubjectstringprioritystringstatus"open" | "pending" | "resolved""open" | "pending" | "resolved"tagsarray<string>messagestringcreated_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 vollständig 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 Ihrer eigenen Spezifikation verwendet wird und echte Endpoints generiert werden.
Mehrsprachige Dokumentation? Legen Sie neben Ihrer Quellspezifikation eine Datei im Format <spec>.<lang>.<ext> (z. B. example-api.fr.yaml) ab. Jamdesk rendert die übersetzte Version, wenn Benutzer die Seite unter /fr/... aufrufen. Weitere Informationen finden Sie unter OpenAPI-Spezifikationen übersetzen.
Auf dieser Seite ist das API Playground aktiviert. Klicken Sie beim obigen Endpoint auf Try it, um die API live zu testen.
Was wird generiert?
Aus einer einzigen openapi-Zeile im Frontmatter generiert Jamdesk automatisch:
- Ein Endpoint-Badge mit Methode und Pfad sowie farblicher Kennzeichnung
- Parameterdokumentation für Pfad-, Query-, Header- und Body-Parameter
- Anfrage- und Antwort-Schemas, einschließlich verschachtelter Objekte und Arrays
- Codebeispiele in cURL, Python, JavaScript, Go, Ruby, C#, Java, Rust und PHP (konfigurierbar über
api.examples.languages) - Authentifizierungsdetails aus den Sicherheitsschemata der Spezifikation
Alle $ref-Referenzen in Ihrer Spezifikation werden automatisch aufgelöst, sodass Sie Schemas wie gewohnt mit components/schemas organisieren können.
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 anschließend openapi: /openapi/your-spec.yaml METHOD /path zum Frontmatter einer beliebigen Seite hinzu. Eine vollständige Anleitung finden Sie im Leitfaden zur OpenAPI-Einrichtung.
Schreiben Sie Ihre Spezifikation in YAML? Überprüfen Sie sie mit dem kostenlosen YAML Validator, um Einrückungs- und Syntaxfehler zu erkennen, bevor der Build sie verarbeitet.