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.
Template per Documentazione API REST è un template in formato Word pubblicato da Management Academy. Template di prompt per documentare un'API REST endpoint per endpoint con parametri, schema, codici di stato ed esempi cURL in markdown stile OpenAPI. Si scarica gratuitamente con un account gratuito.
Cos'è e quando si usa
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.
Cosa contiene il file
# 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}]}'
```
Come si usa, passo per passo
- Scarica il file e aprilo. Resta editabile: si apre con Excel, Word e PowerPoint, e anche con Google Workspace o LibreOffice.
- Compila prima le sezioni obbligatorie. Sono quelle che un committente o un esaminatore guarda per prime: oggetto, responsabili, criteri di accettazione.
- Rigenera con il prompt sui tuoi dati. Copia il prompt di questa pagina, incolla il contesto del progetto e ottieni il documento già compilato.
- Fai rivedere il risultato. Un documento corretto nel metodo ma scollegato dal progetto non regge alla prima domanda: rileggilo con chi il progetto lo conosce.
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.