Se stai creando delle API con Laravel o Lumen, avrai molto probabilmente bisogno di generare un’accurata documentazione per chi dovrà utilizzarle. Che si tratti di un front-end developer, un cliente oppure chiunque altro, non ha importanza: descrivere correttamente il funzionamento delle API permetterà all’utilizzatore di risparmiare moltissimo tempo e a te di alleggerirti molto nella fase di supporto.

Documentazione API: criteri e modalità

Quando si descrivono le API in una documentazione, solitamente è opportuno specificare:

  • la url,
  • il verb
  • eventuali headers
  • body della request
  • tutti i possibili http status code delle response e relativi body

Il nostro consiglio è sempre quello di seguire gli standard. Lo standard per la documentazione delle API più utilizzato è OpenAPI. Le specifiche di OpenAPI descrivono la sintassi e i dati obbligatori necessari per documentare correttamente ogni end-point delle tue API.

Lo strumento che ti suggeriamo di utilizzare per la stesura della documentazione conforme alle specifiche OpenAPI è decisamente Swagger. Tramite lo swagger editor è possibile editare un file yaml contenente le informazioni relative ai tuoi end-point, con le informazioni che abbiamo elencato sopra.

Swagger UI è un pacchetto di file in grado di leggere il file yaml o json definito con lo swagger editor e renderizzarne in html il contenuto, in modo da renderlo facilmente leggibile da chi dovrà leggere la documentazione.

Generare documentazione in automatico

Non hai tempo da perdere? Beh, la stesura della documentazione non è affatto tempo perso, ma esistono comunque soluzioni per risparmiare tempo, generando in automatico la documentazione partendo dalle routes e dai controller della tua applicazione Laravel.

Ad esempio Laravel API Documentation Generator è un package per Laravel che permette di generare documentazione in modo automatico partendo dalle route della tua applicazione.

Una volta installato il package, con un semplice comando viene generata automaticamente una cartella con la documentazione:

php artisan api:gen --routePrefix="settings/api/*"

Questo package usa i blocchi di documentazione dei controller HTTP per creare un elenco dei metodi delle API con le relative descrizioni.

Usando @resource in un blocco di commento prima di ogni controller ci torna utile proprio perché crea un gruppo all’interno della documentazione per tutti i metodi definiti in quel controller, ma non è obbligatorio.

La breve descrizione dopo @resource dovrebbe essere univoca in modo da permettere agli anchor tags di funzionare correttamente per la navigazione all’interno della documentazione.

Prima di ogni metodo all’interno del controller devi avere un commento che descrive il funzionamento del metodo stesso.

In conclusione

Questa seconda soluzione ti permetterà di risparmiare un po’ di tempo anche se comunque dovrai scrivere i descrittivi dei vari metodi. Inoltre il risultato finale non sarà probabilmente perfetto o conforme agli standard OpenAPI.

La scelta finale rimane a te, considerando i tempi, entità del progetto e chi dovrà utilizzare la tua documentazione.