Anfrage- und Antwortbeispiele
Erfahren Sie, wie Sie APIs mit den Komponenten RequestExample und ResponseExample dokumentieren, anhand eines praktischen Support-Ticket-Workflows von Acme.
Verwenden Sie RequestExample und ResponseExample, um die reale API-Nutzung neben Ihren Endpunkt-Dokumentationen anzuzeigen. Die Komponenten können mehrere Sprachen, Antwortstatus und Erläuterungen im Text darstellen.
Beispiel: Ein Support-Ticket abrufen
Dieses Beispiel dokumentiert einen GET /tickets/{ticket_id}-Endpunkt für die Acme Support API.
Anfrage
Verwenden Sie Parameterfelder, um zu beschreiben, was der Endpunkt erwartet. Das Code-Beispiel befindet sich in der rechten Seitenleiste.
ticket_idstringrequiredEindeutige Ticket-ID, die beim Erstellen 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 Ticket-Status (open, pending oder resolved).
created_atstringISO-8601-Zeitstempel für den Zeitpunkt, an dem das Ticket erstellt wurde.
{
"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 Erfolgsantwort und eine Fehlerantwort ein.
- Verwenden Sie realistische Bezeichner und Zeitstempel, damit die Beispiele authentisch wirken.
- Halten Sie die Payloads minimal, damit Leser sie schnell erfassen können.