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 ist ein live generierter Endpunkt auf Basis einer OpenAPI-Spezifikation. Jamdesk erzeugt aus der Spezifikation das Anfrageschema, die Antwortmodelle und die Codebeispiele im rechten Bereich.

Dieses Beispiel verwendet die Acme Support API. Verweisen Sie api.openapi in docs.json auf Ihre Spezifikationsdatei, um Ihre Endpunkte zu generieren.

Mehrsprachige Dokumentation? Legen Sie neben Ihrer Quellspezifikation eine Datei <spec>.<lang>.<ext> ab (z. B. example-api.fr.yaml). Jamdesk rendert die übersetzte Version auf Seiten unter /fr/.... Siehe Übersetzung von OpenAPI-Spezifikationen.

Auf dieser Seite ist der API-Playground aktiviert. Klicken Sie oben auf den Endpunkt auf Try it, um die API live zu testen.

Was generiert wird

Aus einer einzigen openapi-Zeile im Frontmatter erzeugt Jamdesk:

Ein Endpunkt-Badge mit Methode und Pfad, farblich codiert
Parameterdokumentation für Pfad-, Query-, Header- und Body-Parameter
Anfrage- und Antwortschemata, 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 Security Schemes der Spezifikation

Jamdesk löst jedes $ref in Ihrer Spezifikation auf. Organisieren Sie Schemata wie gewohnt mit components/schemas.

Jamdesk rendert Beschreibungen in Ihrer Spezifikation als Markdown, nicht als Rohtext. Beschreibungen von Operationen, Parametern, Request-Bodies, Antworten und Schemata unterstützen dieselben fettgedruckten Texte, 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. Fügen Sie anschließend openapi: /openapi/your-spec.yaml METHOD /path im Frontmatter einer beliebigen Seite hinzu. Vollständige Details finden Sie im OpenAPI-Setup-Leitfaden.

Eine Seite für jede Operation generieren

Richten Sie einen Navigationstab auf die Spezifikation, damit Jamdesk die gesamte Referenz erstellt, statt für jeden Endpunkt eine eigene Seite zu schreiben:

docs.json

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

Jede Operation erhält eine Seite. Die Seitenleiste ist nach Tags gruppiert. Committete .mdx-Dateien haben bei Slug-Kollisionen Vorrang. Sie können dies Seite für Seite übernehmen. Wenn Sie einen Pfad in Ihrer Spezifikation umbenennen, wird die alte URL weitergeleitet, statt zu brechen. Die vollständigen Regeln und aktuellen Grenzen finden Sie unter navigation openapi.

Schreiben Sie Ihre Spezifikation in YAML? Prüfen Sie sie mit dem kostenlosen YAML Validator, um Einrückungs- und Syntaxfehler zu finden, bevor der Build sie parst.