Scrivere la parte che il generatore non può
La documentazione generata risponde a «cosa accetta questo endpoint». Nessuno si è mai bloccato su quella domanda.
API Documentation genera dalle tue collection e ci aggiunge sopra un editor di testo ricco, gestione delle versioni, generazione di snippet, esportazione PDF e link condivisibili.
La metà generata è completa e corretta e da sola non aiuta nessuno. Ciò che blocca uno sviluppatore non è mai l’elenco dei parametri.
Ordina il documento per chi legge la prima volta
Gli elenchi di endpoint sono di solito alfabetici, ed è l’ordine che non serve a nessuno. Metti il documento nell’ordine in cui si integra:
- Come autenticarsi, con un esempio completo e funzionante.
- L’unica chiamata che dimostra che la configurazione funziona: la richiesta più piccola che restituisce qualcosa.
- Il flusso principale, nell’ordine in cui accade.
- Tutto il resto in ordine alfabetico, perché a quel punto chi legge sta cercando, non leggendo.
Chi arriva a una prima chiamata riuscita diventa paziente. Chi non riesce ad autenticarsi in dieci minuti scrive al supporto e resta irritato.
Documenta gli errori, non il successo
Ogni documentazione generata descrive il 200. Quasi nessuna descrive il 409 che significa che l’e-mail è già registrata, né cosa dovrebbe farne il client: riprovare, mostrare un messaggio o ripiegare su un’altra chiamata.
Scrivi la tabella degli errori a mano. È la sezione più letta e l’unica che accorcia le conversazioni col supporto.
Quando fissare una versione
La gestione delle versioni si guadagna il posto il giorno in cui qualcuno fuori dal tuo team costruisce sull’API. Fissa una versione in quel momento, non a una milestone di rilascio.
Il motivo è pratico: quando in seguito cambierai un campo, chi ha integrato il trimestre scorso ha bisogno del documento com’era, non di una voce di changelog che spiega che si è spostato. Condividere un link a una versione specifica non costa nulla e chiude la discussione prima che nasca.
Per qualsiasi cosa con lettori esterni, condividi un link invece di esportare un PDF. Il link segue la versione; un PDF inizia a essere sbagliato il giorno dopo l’invio.
Domande frequenti
In che ordine deve stare la documentazione?
Autenticazione con esempio completo, poi la chiamata più piccola che dimostra che funziona, poi il flusso principale in sequenza, poi tutto il resto in ordine alfabetico. Alfabetico dall’inizio non serve a nessuno che integra per la prima volta.
Cosa devo scrivere a mano?
Gli errori e il motivo per cui ogni endpoint esiste. Il generatore copre i parametri per intero; nessuno si è mai bloccato su un elenco di parametri e tutti si sono bloccati su un 409 non spiegato.
Quando dovrei fissare una nuova versione?
Il giorno in cui qualcuno fuori dal team inizia a costruire sull’API, non a una milestone di rilascio. Quella persona avrà bisogno del documento com’era al momento dell’integrazione, non di una nota che dice che un campo si è spostato.
