Scrittore di Documentazione API
Lo Scrittore di Documentazione API produce documentazione strutturata e pensata per gli sviluppatori, dedicata a REST API. A partire dai dettagli dei tuoi endpoint o dal codice, genera descrizioni, tabelle di parametri, esempi di request/response, riferimenti ai codici di errore e note sull'autenticazione, in un formato pronto per la pubblicazione.
Sviluppatori backend, API product manager e technical writer usano questo template quando lanciano nuove API, fanno onboarding di sviluppatori esterni o aggiornano la documentazione dopo modifiche agli endpoint. È particolarmente utile quando la documentazione è rimasta indietro rispetto all'implementazione reale e serve un aggiornamento completo.
Il prompt produce documentazione in un formato standardizzato che segue le convenzioni del settore (simile alla documentazione di Stripe e Twilio). Include esempi cURL per test rapidi, snippet SDK in diversi linguaggi, e documenta esplicitamente i casi di errore, la sezione che nella documentazione scritta a mano è quasi sempre incompleta.
Questo prompt e' solo il punto di partenza
Analizzalo con l'AI, ottimizzalo con un click, tieni traccia delle versioni e costruisci la tua libreria.
Il Prompt
Scrivi una documentazione API completa per i seguenti endpoint:
**URL Base dell'API**: [URL BASE, es. https://api.example.com/v1]
**Metodo di Autenticazione**: [METODO AUTH, es. Bearer token, API key nell'header, OAuth2]
**Dettagli Endpoint**:
```
[INCOLLA IL CODICE DELLA ROUTE, LO SPEC OPENAPI, O DESCRIVI L'ENDPOINT:
Method: POST
Path: /users
Purpose: Creare un nuovo account utente
Campi del request body: email, password, name
Response: oggetto utente con id, email, name, created_at]
```
Per ogni endpoint, genera documentazione con questa struttura:
### [METHOD] [PATH]
**Descrizione**: Un paragrafo che spiega cosa fa questo endpoint e quando usarlo.
**Autenticazione**: Obbligatoria o opzionale, e di quale tipo.
**Parametri della Request**:
| Parametro | Tipo | Obbligatorio | Descrizione | Esempio |
|-----------|------|--------------|-------------|---------|
**Request Body** (se applicabile):
| Campo | Tipo | Obbligatorio | Vincoli | Descrizione |
|-------|------|--------------|---------|-------------|
**Esempio di Request**:
```bash
curl -X [METHOD] [FULL_URL] \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{ esempio realistico del body }'
```
**Risposta Positiva** (codice di stato):
```json
{ esempio realistico di risposta }
```
**Risposte di Errore**:
| Codice di Stato | Codice Errore | Descrizione | Risoluzione |
|-----------------|---------------|-------------|-------------|
**Rate Limiting**: Indica eventuali limiti di frequenza applicati.
**Note**: Eventuali avvertenze, avvisi di deprecazione o endpoint correlati da tenere in considerazione.
Includi almeno 3 scenari di errore (errore di validazione, errore di autenticazione, risorsa non trovata) con body di risposta realistici.Consigli d'uso
- Incolla il codice reale della route: Invece di descrivere l'endpoint manualmente, incolla direttamente la funzione handler. L'AI estrarrà parametri, regole di validazione e casi di errore dal codice stesso.
- Specifica il formato della tua documentazione: Se usi un formato specifico (OpenAPI/Swagger, API Blueprint o un formato personalizzato), indicalo così l'output sarà coerente.
- Raggruppa più endpoint: Elenca diversi endpoint correlati (es. tutte le operazioni CRUD per una risorsa) in un unico prompt per garantire uno stile di documentazione coerente.
- Verifica gli esempi: Testa sempre gli esempi cURL sulla tua API reale. I modelli AI possono produrre body di richiesta sintatticamente corretti ma logicamente errati.
- Aggiungi al version control: Salva la documentazione generata come file markdown accanto al tuo codice, così resta sincronizzata con le modifiche.
Ottieni di piu' da questo prompt
Salvalo, analizzalo con l'AI, ottimizzalo e tieni traccia di ogni versione. Gratis per iniziare.