PREMIUM

Template per Documentazione API REST

Serve a backend developer e technical writer che devono documentare un'API in modo che sia subito usabile da chi la integra. Concreto: fornisci gli endpoint e i modelli dati e ottieni, per ciascuna risorsa, una scheda completa con metodo e path, parametri (path/query/body) in tabella, schema della risposta, tabella dei codici di stato ed esempio cURL, in markdown allineato alle convenzioni OpenAPI.

#api #rest #documentazione #openapi #endpoint

Scarica il template Gratis con la registrazione Compila con i tuoi dati

Esempio di output

# API Riferimento - Risorsa: Ordini

## POST /v1/ordini
Crea un nuovo ordine.

**Autenticazione:** Bearer token (header Authorization)

### Parametri (body)
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| cliente_id | string (uuid) | Si | Identificativo del cliente |
| righe | array<Riga> | Si | Elenco articoli ordinati |
| note | string | No | Note libere, max 500 caratteri |

### Risposta 201 Created
```json
{
  "id": "ord_8f3a",
  "stato": "in_lavorazione",
  "totale": 149.90
}
```

### Codici di stato
| Codice | Significato | Quando |
|---|---|---|
| 201 | Created | Ordine creato |
| 400 | Bad Request | Body non valido |
| 401 | Unauthorized | Token mancante/scaduto |
| 422 | Unprocessable | cliente_id inesistente |

### Esempio cURL
```bash
curl -X POST https://api.esempio.it/v1/ordini \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"cliente_id":"cli_12","righe":[{"sku":"AB1","qta":2}]}'
```

Domande frequenti

Inventa endpoint o campi non forniti?

No: documenta solo gli endpoint, i parametri e i campi che fornisci. Se manca un'informazione essenziale (tipo di un campo, autenticazione) la marca con [DA SPECIFICARE] invece di assumere un valore.

Include esempi eseguibili?

Si: per ogni endpoint genera un esempio cURL coerente con metodo, header di autenticazione e body dichiarati, piu un esempio di risposta JSON con i campi descritti.

E compatibile con OpenAPI?

Si: usa la terminologia e la struttura tipiche di OpenAPI (path, parametri per posizione, schema, codici di stato) cosi che la documentazione sia facilmente trasponibile in una specifica formale.

Vuoi un template su misura?

Costruiscine uno in poche domande — con la struttura corretta per il tuo standard.

Crea il tuo template