Beispiele für Anfragen und Antworten
Erfahren Sie, wie Sie APIs mit RequestExample- und ResponseExample-Komponenten anhand eines praktischen Acme-Support-Ticket-Workflows dokumentieren.
Verwenden Sie RequestExample und ResponseExample, um die praktische API-Nutzung zusammen mit Ihrer Endpoint-Dokumentation zu zeigen. Die Komponenten unterstützen mehrere Programmiersprachen, Antwortstatus und Inline-Erklärungen.
Beispiel: Support-Ticket abrufen
Dieses Beispiel dokumentiert einen einfachen GET /tickets/{ticket_id}-Endpoint für die Acme Support API.
Anfrage
Verwenden Sie Parameterfelder, um zu beschreiben, was der Endpoint erwartet. Das Codebeispiel befindet sich in der rechten Seitenleiste.
ticket_idstringrequiredEindeutige Ticket-ID, die bei der Erstellung des Tickets zurückgegeben wurde.
curl -X GET https://api.acme.com/v1/tickets/tkt_9S8L2 \
-H "Authorization: Bearer $ACME_TOKEN"Antwort
Verwenden Sie Antwortfelder, um die wichtigsten von der API zurückgegebenen Attribute zu dokumentieren.
idstringrequiredEindeutige Ticket-ID.
statusstringAktueller Ticketstatus (open, pending oder resolved).
created_atstringISO-8601-Zeitstempel der Ticketerstellung.
{
"id": "tkt_9S8L2",
"customer_id": "cus_2X9W8",
"subject": "Export stuck on step 3",
"priority": "high",
"status": "open",
"created_at": "2026-02-04T16:12:00Z"
}Tipps
- Fügen Sie mindestens eine erfolgreiche Antwort und eine Fehlerantwort hinzu.
- Verwenden Sie realistische IDs und Zeitstempel, damit die Beispiele realistisch wirken.
- Halten Sie Payloads minimal, damit Leser sie schnell überfliegen können.