Esempi di richieste e risposte
Scopri come documentare le API con i componenti RequestExample e ResponseExample usando un flusso pratico per i ticket di supporto Acme.
Usa RequestExample e ResponseExample per mostrare l'utilizzo reale delle API insieme alla documentazione degli endpoint. I componenti supportano più linguaggi, stati della risposta e spiegazioni inline.
Esempio: recuperare un ticket di supporto
Questo esempio documenta un semplice endpoint GET /tickets/{ticket_id} per l'API di supporto Acme.
Richiesta
Usa i campi dei parametri per descrivere ciò che l'endpoint si aspetta. L'esempio di codice si trova nella barra laterale destra.
ticket_idstringrequiredIdentificatore univoco del ticket restituito al momento della creazione del ticket.
curl -X GET https://api.acme.com/v1/tickets/tkt_9S8L2 \
-H "Authorization: Bearer $ACME_TOKEN"Risposta
Usa i campi della risposta per documentare gli attributi più importanti restituiti dall'API.
idstringrequiredIdentificatore univoco del ticket.
statusstringStato attuale del ticket (open, pending o resolved).
created_atstringTimestamp ISO 8601 della creazione del ticket.
{
"id": "tkt_9S8L2",
"customer_id": "cus_2X9W8",
"subject": "Export stuck on step 3",
"priority": "high",
"status": "open",
"created_at": "2026-02-04T16:12:00Z"
}Suggerimenti
- Includi almeno una risposta di successo e una risposta di errore.
- Usa identificatori e timestamp realistici per rendere concreti gli esempi.
- Mantieni i payload essenziali, così i lettori possono esaminarli rapidamente.