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.
Compila i campi del prompt
Inserisci i tuoi dati: il prompt si completa qui sotto, pronto da copiare.
Claude
· Anthropic
<role>
Agisci come un backend developer e technical writer senior esperto di progettazione e documentazione di API REST secondo le convenzioni OpenAPI.
</role>
<task>
Genera la documentazione di riferimento dell'API, organizzata per risorsa e poi per singolo endpoint. Per ogni endpoint descrivi metodo e path, autenticazione richiesta, parametri (path, query, body) in tabella con tipo e obbligatorieta, lo schema della risposta di successo in JSON, una tabella dei codici di stato con il loro significato contestuale e un esempio cURL eseguibile.
</task>
<context>
API: [nome e versione, es. v1]. Base URL: [es. https://api.esempio.it]. Schema di autenticazione: [es. Bearer token, API key in header]. Risorse ed endpoint da documentare: [elenco metodo+path, es. POST /ordini, GET /ordini/{id}]. Modelli dati/campi: [campi con tipo e vincoli per ciascuna risorsa]. Comportamenti speciali: [paginazione, rate limit, idempotenza, errori specifici].
</context>
<output_format>
Restituisci markdown pronto per un portale developer. Per ogni risorsa un titolo H1 'API Riferimento - Risorsa: [nome]'. Per ogni endpoint un H2 con 'METODO /path' e una riga di descrizione, poi: riga '**Autenticazione:**'; H3 'Parametri' con tabella | Campo | Tipo | Obbligatorio | Descrizione | (separata per path/query/body se necessario); H3 'Risposta [codice]' con blocco di codice json; H3 'Codici di stato' con tabella | Codice | Significato | Quando |; H3 'Esempio cURL' con blocco di codice bash coerente con i parametri.
</output_format>
<constraints>
Documenta esclusivamente gli endpoint, i parametri e i campi forniti: non inventarne. Dove un tipo, un vincolo o lo schema di autenticazione non e indicato usa [DA SPECIFICARE]. Gli esempi cURL e JSON devono essere coerenti tra loro e con i campi dichiarati (stessi nomi, stessi tipi). Usa tipi precisi (string, integer, boolean, array<Tipo>, formati come uuid/date-time). Non promettere comportamenti non dichiarati (es. rate limit) se non forniti nel contesto. Tutto in italiano per le descrizioni; nomi di campi ed esempi tecnici restano nel formato dell'API.
</constraints>
<tone>
Professionale, conciso, orientato all'integratore.
</tone>
DeepSeek
· DeepSeek
Ruolo: Agisci come un backend developer e technical writer senior esperto di progettazione e documentazione di API REST secondo le convenzioni OpenAPI.
Obiettivo: Genera la documentazione di riferimento dell'API, organizzata per risorsa e poi per singolo endpoint. Per ogni endpoint descrivi metodo e path, autenticazione richiesta, parametri (path, query, body) in tabella con tipo e obbligatorieta, lo schema della risposta di successo in JSON, una tabella dei codici di stato con il loro significato contestuale e un esempio cURL eseguibile.
Contesto: API: [nome e versione, es. v1]. Base URL: [es. https://api.esempio.it]. Schema di autenticazione: [es. Bearer token, API key in header]. Risorse ed endpoint da documentare: [elenco metodo+path, es. POST /ordini, GET /ordini/{id}]. Modelli dati/campi: [campi con tipo e vincoli per ciascuna risorsa]. Comportamenti speciali: [paginazione, rate limit, idempotenza, errori specifici].
Formato output: Restituisci markdown pronto per un portale developer. Per ogni risorsa un titolo H1 'API Riferimento - Risorsa: [nome]'. Per ogni endpoint un H2 con 'METODO /path' e una riga di descrizione, poi: riga '**Autenticazione:**'; H3 'Parametri' con tabella | Campo | Tipo | Obbligatorio | Descrizione | (separata per path/query/body se necessario); H3 'Risposta [codice]' con blocco di codice json; H3 'Codici di stato' con tabella | Codice | Significato | Quando |; H3 'Esempio cURL' con blocco di codice bash coerente con i parametri.
Vincoli & regole: Documenta esclusivamente gli endpoint, i parametri e i campi forniti: non inventarne. Dove un tipo, un vincolo o lo schema di autenticazione non e indicato usa [DA SPECIFICARE]. Gli esempi cURL e JSON devono essere coerenti tra loro e con i campi dichiarati (stessi nomi, stessi tipi). Usa tipi precisi (string, integer, boolean, array<Tipo>, formati come uuid/date-time). Non promettere comportamenti non dichiarati (es. rate limit) se non forniti nel contesto. Tutto in italiano per le descrizioni; nomi di campi ed esempi tecnici restano nel formato dell'API.
Tono & stile: Professionale, conciso, orientato all'integratore.
Gemini
· Google
## Ruolo
Agisci come un backend developer e technical writer senior esperto di progettazione e documentazione di API REST secondo le convenzioni OpenAPI.
## Contesto
API: [nome e versione, es. v1]. Base URL: [es. https://api.esempio.it]. Schema di autenticazione: [es. Bearer token, API key in header]. Risorse ed endpoint da documentare: [elenco metodo+path, es. POST /ordini, GET /ordini/{id}]. Modelli dati/campi: [campi con tipo e vincoli per ciascuna risorsa]. Comportamenti speciali: [paginazione, rate limit, idempotenza, errori specifici].
## Obiettivo
Genera la documentazione di riferimento dell'API, organizzata per risorsa e poi per singolo endpoint. Per ogni endpoint descrivi metodo e path, autenticazione richiesta, parametri (path, query, body) in tabella con tipo e obbligatorieta, lo schema della risposta di successo in JSON, una tabella dei codici di stato con il loro significato contestuale e un esempio cURL eseguibile.
## Tono & stile
Professionale, conciso, orientato all'integratore.
## Formato output
Restituisci markdown pronto per un portale developer. Per ogni risorsa un titolo H1 'API Riferimento - Risorsa: [nome]'. Per ogni endpoint un H2 con 'METODO /path' e una riga di descrizione, poi: riga '**Autenticazione:**'; H3 'Parametri' con tabella | Campo | Tipo | Obbligatorio | Descrizione | (separata per path/query/body se necessario); H3 'Risposta [codice]' con blocco di codice json; H3 'Codici di stato' con tabella | Codice | Significato | Quando |; H3 'Esempio cURL' con blocco di codice bash coerente con i parametri.
## Vincoli & regole
Documenta esclusivamente gli endpoint, i parametri e i campi forniti: non inventarne. Dove un tipo, un vincolo o lo schema di autenticazione non e indicato usa [DA SPECIFICARE]. Gli esempi cURL e JSON devono essere coerenti tra loro e con i campi dichiarati (stessi nomi, stessi tipi). Usa tipi precisi (string, integer, boolean, array<Tipo>, formati come uuid/date-time). Non promettere comportamenti non dichiarati (es. rate limit) se non forniti nel contesto. Tutto in italiano per le descrizioni; nomi di campi ed esempi tecnici restano nel formato dell'API.
Grok
· xAI
## Ruolo
Agisci come un backend developer e technical writer senior esperto di progettazione e documentazione di API REST secondo le convenzioni OpenAPI.
## Obiettivo
Genera la documentazione di riferimento dell'API, organizzata per risorsa e poi per singolo endpoint. Per ogni endpoint descrivi metodo e path, autenticazione richiesta, parametri (path, query, body) in tabella con tipo e obbligatorieta, lo schema della risposta di successo in JSON, una tabella dei codici di stato con il loro significato contestuale e un esempio cURL eseguibile.
## Contesto
API: [nome e versione, es. v1]. Base URL: [es. https://api.esempio.it]. Schema di autenticazione: [es. Bearer token, API key in header]. Risorse ed endpoint da documentare: [elenco metodo+path, es. POST /ordini, GET /ordini/{id}]. Modelli dati/campi: [campi con tipo e vincoli per ciascuna risorsa]. Comportamenti speciali: [paginazione, rate limit, idempotenza, errori specifici].
## Formato output
Restituisci markdown pronto per un portale developer. Per ogni risorsa un titolo H1 'API Riferimento - Risorsa: [nome]'. Per ogni endpoint un H2 con 'METODO /path' e una riga di descrizione, poi: riga '**Autenticazione:**'; H3 'Parametri' con tabella | Campo | Tipo | Obbligatorio | Descrizione | (separata per path/query/body se necessario); H3 'Risposta [codice]' con blocco di codice json; H3 'Codici di stato' con tabella | Codice | Significato | Quando |; H3 'Esempio cURL' con blocco di codice bash coerente con i parametri.
## Vincoli & regole
Documenta esclusivamente gli endpoint, i parametri e i campi forniti: non inventarne. Dove un tipo, un vincolo o lo schema di autenticazione non e indicato usa [DA SPECIFICARE]. Gli esempi cURL e JSON devono essere coerenti tra loro e con i campi dichiarati (stessi nomi, stessi tipi). Usa tipi precisi (string, integer, boolean, array<Tipo>, formati come uuid/date-time). Non promettere comportamenti non dichiarati (es. rate limit) se non forniti nel contesto. Tutto in italiano per le descrizioni; nomi di campi ed esempi tecnici restano nel formato dell'API.
## Tono & stile
Professionale, conciso, orientato all'integratore.
## Verbosità
Fornisci una risposta completa e dettagliata, coerente con il formato richiesto.
Mistral
· Mistral AI
## Ruolo
Agisci come un backend developer e technical writer senior esperto di progettazione e documentazione di API REST secondo le convenzioni OpenAPI.
## Obiettivo
Genera la documentazione di riferimento dell'API, organizzata per risorsa e poi per singolo endpoint. Per ogni endpoint descrivi metodo e path, autenticazione richiesta, parametri (path, query, body) in tabella con tipo e obbligatorieta, lo schema della risposta di successo in JSON, una tabella dei codici di stato con il loro significato contestuale e un esempio cURL eseguibile.
## Contesto
API: [nome e versione, es. v1]. Base URL: [es. https://api.esempio.it]. Schema di autenticazione: [es. Bearer token, API key in header]. Risorse ed endpoint da documentare: [elenco metodo+path, es. POST /ordini, GET /ordini/{id}]. Modelli dati/campi: [campi con tipo e vincoli per ciascuna risorsa]. Comportamenti speciali: [paginazione, rate limit, idempotenza, errori specifici].
## Formato output
Restituisci markdown pronto per un portale developer. Per ogni risorsa un titolo H1 'API Riferimento - Risorsa: [nome]'. Per ogni endpoint un H2 con 'METODO /path' e una riga di descrizione, poi: riga '**Autenticazione:**'; H3 'Parametri' con tabella | Campo | Tipo | Obbligatorio | Descrizione | (separata per path/query/body se necessario); H3 'Risposta [codice]' con blocco di codice json; H3 'Codici di stato' con tabella | Codice | Significato | Quando |; H3 'Esempio cURL' con blocco di codice bash coerente con i parametri.
## Vincoli & regole
Documenta esclusivamente gli endpoint, i parametri e i campi forniti: non inventarne. Dove un tipo, un vincolo o lo schema di autenticazione non e indicato usa [DA SPECIFICARE]. Gli esempi cURL e JSON devono essere coerenti tra loro e con i campi dichiarati (stessi nomi, stessi tipi). Usa tipi precisi (string, integer, boolean, array<Tipo>, formati come uuid/date-time). Non promettere comportamenti non dichiarati (es. rate limit) se non forniti nel contesto. Tutto in italiano per le descrizioni; nomi di campi ed esempi tecnici restano nel formato dell'API.
## Tono & stile
Professionale, conciso, orientato all'integratore.
## Verbosità
Fornisci una risposta completa e dettagliata, coerente con il formato richiesto.
ChatGPT
· OpenAI
## Ruolo
Agisci come un backend developer e technical writer senior esperto di progettazione e documentazione di API REST secondo le convenzioni OpenAPI.
## Obiettivo
Genera la documentazione di riferimento dell'API, organizzata per risorsa e poi per singolo endpoint. Per ogni endpoint descrivi metodo e path, autenticazione richiesta, parametri (path, query, body) in tabella con tipo e obbligatorieta, lo schema della risposta di successo in JSON, una tabella dei codici di stato con il loro significato contestuale e un esempio cURL eseguibile.
## Contesto
API: [nome e versione, es. v1]. Base URL: [es. https://api.esempio.it]. Schema di autenticazione: [es. Bearer token, API key in header]. Risorse ed endpoint da documentare: [elenco metodo+path, es. POST /ordini, GET /ordini/{id}]. Modelli dati/campi: [campi con tipo e vincoli per ciascuna risorsa]. Comportamenti speciali: [paginazione, rate limit, idempotenza, errori specifici].
## Formato output
Restituisci markdown pronto per un portale developer. Per ogni risorsa un titolo H1 'API Riferimento - Risorsa: [nome]'. Per ogni endpoint un H2 con 'METODO /path' e una riga di descrizione, poi: riga '**Autenticazione:**'; H3 'Parametri' con tabella | Campo | Tipo | Obbligatorio | Descrizione | (separata per path/query/body se necessario); H3 'Risposta [codice]' con blocco di codice json; H3 'Codici di stato' con tabella | Codice | Significato | Quando |; H3 'Esempio cURL' con blocco di codice bash coerente con i parametri.
## Vincoli & regole
Documenta esclusivamente gli endpoint, i parametri e i campi forniti: non inventarne. Dove un tipo, un vincolo o lo schema di autenticazione non e indicato usa [DA SPECIFICARE]. Gli esempi cURL e JSON devono essere coerenti tra loro e con i campi dichiarati (stessi nomi, stessi tipi). Usa tipi precisi (string, integer, boolean, array<Tipo>, formati come uuid/date-time). Non promettere comportamenti non dichiarati (es. rate limit) se non forniti nel contesto. Tutto in italiano per le descrizioni; nomi di campi ed esempi tecnici restano nel formato dell'API.
## Tono & stile
Professionale, conciso, orientato all'integratore.
## Verbosità
Fornisci una risposta completa e dettagliata, coerente con il formato richiesto.
Perplexity
· Perplexity
Genera la documentazione di riferimento dell'API, organizzata per risorsa e poi per singolo endpoint. Per ogni endpoint descrivi metodo e path, autenticazione richiesta, parametri (path, query, body) in tabella con tipo e obbligatorieta, lo schema della risposta di successo in JSON, una tabella dei codici di stato con il loro significato contestuale e un esempio cURL eseguibile.
Ruolo: Agisci come un backend developer e technical writer senior esperto di progettazione e documentazione di API REST secondo le convenzioni OpenAPI.
Contesto: API: [nome e versione, es. v1]. Base URL: [es. https://api.esempio.it]. Schema di autenticazione: [es. Bearer token, API key in header]. Risorse ed endpoint da documentare: [elenco metodo+path, es. POST /ordini, GET /ordini/{id}]. Modelli dati/campi: [campi con tipo e vincoli per ciascuna risorsa]. Comportamenti speciali: [paginazione, rate limit, idempotenza, errori specifici].
Formato output: Restituisci markdown pronto per un portale developer. Per ogni risorsa un titolo H1 'API Riferimento - Risorsa: [nome]'. Per ogni endpoint un H2 con 'METODO /path' e una riga di descrizione, poi: riga '**Autenticazione:**'; H3 'Parametri' con tabella | Campo | Tipo | Obbligatorio | Descrizione | (separata per path/query/body se necessario); H3 'Risposta [codice]' con blocco di codice json; H3 'Codici di stato' con tabella | Codice | Significato | Quando |; H3 'Esempio cURL' con blocco di codice bash coerente con i parametri.
Vincoli & regole: Documenta esclusivamente gli endpoint, i parametri e i campi forniti: non inventarne. Dove un tipo, un vincolo o lo schema di autenticazione non e indicato usa [DA SPECIFICARE]. Gli esempi cURL e JSON devono essere coerenti tra loro e con i campi dichiarati (stessi nomi, stessi tipi). Usa tipi precisi (string, integer, boolean, array<Tipo>, formati come uuid/date-time). Non promettere comportamenti non dichiarati (es. rate limit) se non forniti nel contesto. Tutto in italiano per le descrizioni; nomi di campi ed esempi tecnici restano nel formato dell'API.
Tono & stile: Professionale, conciso, orientato all'integratore.
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 prompt su misura?
Costruiscine uno in poche domande — e adattalo a ogni modello.