Come Generare la Documentazione per un'API, con Laravel API Documentation Generator!

Tra i vari package interessanti trovati in giro su Internet nell’ultimo periodo, ne ho trovato uno fantastico dedicato alla generazione di documentazione per API realizzate con Laravel.

Il package, in modo del tutto inaspettato e degno della migliore delle fantasie, si chiama Laravel API Documentation Generator, di mpociot. Fa uso del buon Documentarian, sempre dello stesso autore.

In questo breve articolo scopriremo come installarlo, configurarlo e farlo funzionare.

Installazione

Per installare il package, come di consueto, dobbiamo usare Composer:

composer require mpociot/laravel-apidoc-generator

e subito dopo aggiungere il Service Provider del package al nostro file config/app.php.

MpociotApiDocApiDocGeneratorServiceProvider::class,

Nulla di più!

Configurazione ed Uso

L’intero package si basa su un semplice comando Artisan: api:generate. Eccone di seguito un esempio:

$ php artisan api:generate –routePrefix=”api/v1/*”

Tale comando si occupa fattivamente di generare la documentazione ed accetta una serie di opzioni per una maggiore personalizzazione del risultato finale.

• output: il percorso dove salvare la documentazione generata. Il valore di default è public/docs;
• routePrefix: il prefisso della route da prendere in considerazione. Si può usare il carattere * come wildcard;
• routes: le route per le quali generare la documentazione (da usare solo se non si è specificato un prefisso con routePrefix);
• actAsUserId: l’ID utente da usare per effettuare la chiamata e di cui usare le risposte;
• router: il router da usare in fase di processing (può essere Laravel o Dingo, di default è Laravel);
• bindings: elenco dei binding da usare durante la fase di processing (il formato da usare è binding_uno:id|binding_due:id);

Dal Codice alla Documentazione

Di base, il package prende il contenuto dei docblock presenti nei controller e li formatta in modo “comprensibile” all’essere umano.

Supponiamo di avere un metodo foo() (collegato ad una route settings/api/tokens) come questo di seguito:

/**
* This is the short description
*
* This can be an optional longer description of your API call, used within the documentation.
*
*/
public function foo()

Una volta dato in pasto il codice a Laravel API Documentation Generator, ecco quale sarà il risultato finale:

Un’altra cosa molto interessante è l’integrazione con le Request personalizzate che possiamo creare per questo o quel metodo. Nello specifico, l’integrazione riguarda le rules() che andiamo a specificare per la richiesta.

Anche in questo caso la documentazione ci porta un ottimo esempio come riferimento.

public function rules()
{
return [
‘title’ => ‘required|max:255’,
‘body’ => ‘required’,
‘type’ => ‘in:foo,bar’,
‘thumbnail’ => ‘required_if:type,foo|image’,
];
}

Tale codice verrà automaticamente interpretato dal generatore e riportato, sulla documentazione, come

Niente male, vero?

Un’ultima cosa da dire riguardo al generatore, molto interessante, è che vengono prese in considerazione anche le risposte dalle API stesse. In questo, l’opzione actAsUserId ci ritorna utilissima perché ci permette, insieme ad un adeguato seeding del database, di riportare sulle API delle risposte di esempio il più possibile vicine ad un caso d’uso reale.

Aggiornamento

Una volta generata la documentazione, questa verrà messa nella cartella di output scelta in fase di configurazione. Verrà generato anche un indice, nel file index.md (di default in public/docs).

Subito dopo questa prima fase sarà possibile modificare i file generati come meglio si crede. Una volta sistemate queste ultime cose, sarà possibile eseguire il comando

$ php artisan api:update

per generare, a partire dai file .md, dei file statici .html che potranno essere caricati nel nostro server su cui mostrare documentazione. Tale comando accetta un’opzione --location, che permette di specificare dove posizionare l’html statico generato.

Bingo!