In questo Programmazione con la serie Yii2, Sto guidando i lettori sull'uso di Yii2 Framework per PHP. Potresti anche essere interessato al mio Introduzione al framework Yii, che rivede i vantaggi di Yii e include una panoramica delle novità in Yii 2.x.
Benvenuto! Recentemente, ho scritto sulla creazione di API REST per l'applicazione Yii e ho ampliato le API personalizzate per la nostra applicazione di serie di avvio, Meeting Planner.
Nel tutorial di oggi, ti presenterò l'estensione apidoc di Yii, che genera automaticamente una documentazione sfogliabile per il tuo codice. Lo userò per generare documentazione API per Meeting Planner.
Iniziare
Installare apidoc è facile. Come mostrato sopra, devi semplicemente aggiungere il pacchetto usando il compositore.
Oltre a generare documentazione dal codice, è anche in grado di generare documentazione da markdown e trasformarla in PDF.
Ad esempio, esiste la documentazione di Yii Framework, la documentazione tipica del codice:
Ed ecco la Guida Yii2, che credo sia generata dal markdown qui e integrata con la documentazione del codice per una facile navigazione:
Ecco la sintassi della documentazione supportata da apidoc; è basato su phpdoc.
Ironia della sorte, la documentazione per apidoc non è ancora completa, ma è abbastanza facile da usare per la documentazione automatica di base.
Generazione della documentazione API
Se hai seguito la mia serie di startup, sei consapevole che sto costruendo una vasta API per supportare app mobili, ecc. Apidoc è il modo ideale per me di mantenere una documentazione dinamica automatizzata per questo.
Certamente ci sono molti altri servizi web che ti aiutano a documentare la tua API, ma ho scoperto che l'apidoc di Yii ha funzionato bene per le mie esigenze e ho apprezzato il tema in stile phpdoc che usano.
Utilizzando uno stile di commento standard è probabile che altri servizi saranno in grado di creare facilmente la documentazione dal codice di Meeting Planner se mai desidero utilizzarli.
Creazione di blocchi di commenti
Fondamentalmente, si creano commenti all'interno del codice che apidoc utilizza per creare la documentazione. È descritto nella guida allo stile di codifica Yii.
Metti un blocco di commenti nella parte superiore di ogni file come questo:
E tu metti un blocco di commenti sopra ogni controller o definizione del modello:
/ ** * UserTokenController fornisce funzionalità API per la registrazione, l'eliminazione e la verifica * * @author Jeff Reifman * @since 0.1 * / class UserTokenController estende il controller
Quindi, si posiziona un blocco di commenti dettagliato sopra ciascun metodo, che include parametri, valori di ritorno ed eccezioni:
/ ** * Registra un nuovo utente con un social esterno Oauth_token * * @param string $ firma l'hash generato con app_secret * @param stringa $ app_id nell'intestazione, l'ID dell'applicazione segreta condivisa * @param stringa $ email nell'intestazione, indirizzo email * @param stringa $ firstname nell'intestazione, nome * @param stringa $ lastname nell'intestazione, cognome * @param stringa $ oauth_token nell'intestazione, il token restituito da Facebook durante OAuth per questo utente * @param stringa $ origine nell'intestazione, la fonte che il $ oauth_token proviene da es "facebook" ad es. [$ oauth_token] * @return obj $ identityObj con user_id e user_token * @throws Exception non ancora implementata * / public function actionRegister ($ signature, $ app_id = ", $ email =", $ firstname = ", $ lastname =", $ oauth_token = ", $ source =")
È necessario seguire il layout prescritto come descritto per alimentare correttamente Apidoc.
Utilizzo degli argomenti dei segnaposto per la documentazione API
Il team di Yii ha sviluppato apidoc per generare documentazione sul codice. Tuttavia, come ho scritto in Securing Your API, tutti gli argomenti tranne l'hash signature sono stati spostati negli header http. Questi sono invisibili all'apidoc. Pertanto, per generare documentazione API, ho deciso di utilizzare una soluzione alternativa.
Come puoi vedere, includo gli argomenti fittizi nei metodi e poi nei commenti che vengono inviati come intestazioni o "nell'intestazione".
In un attimo, vedrai come questo generalmente funziona per la documentazione API, anche se non è uno stile di codifica ottimale.
Passiamo ad usare effettivamente apidoc per generare la documentazione.
Generazione della documentazione
È possibile rivedere i comandi apidoc eseguendolo senza argomenti:
$ ./vendor/bin/apidoc Questa è la versione 2.0.10 di Yii. Sono disponibili i seguenti comandi: - api Genera documentazione API di classe. api / index (predefinito) File di documentazione dell'API Renders - guida Questo comando può eseguire il rendering della documentazione memorizzata come file di markdown come la guida / indice di yii (predefinito) File di documentazione dell'API Renders - help Fornisce informazioni di aiuto sui comandi della console. help / index (default) Visualizza i comandi disponibili o le informazioni dettagliate Per vedere l'aiuto di ciascun comando, immettere: help apidoc
Userò l'opzione API, e qui ci sono le configurazioni che puoi fare:
$ ./vendor/bin/apidoc help api DESCRIZIONE Documentazione dell'API Renders file USAGE apidoc api [... options ...] - sourceDirs (richiesto): array $ sourceDirs - targetDir (richiesto): string $ targetDir OPTIONS --appconfig: stringa percorso del file di configurazione dell'applicazione personalizzata. Se non impostato, viene utilizzata la configurazione dell'applicazione predefinita. --color: boolean, 0 o 1 se abilitare il colore ANSI nell'output. Se non impostato, il colore ANSI sarà abilitato solo per i terminali che lo supportano. --exclude: string | file array da escludere. --guide: stringa url a cui si trovano i file guida --guidePrefix: string (predefinito a 'guide-') prefisso per anteporre a tutti i nomi dei file guida. --help, -h: boolean, 0 o 1 se visualizzare le informazioni della guida sul comando corrente. --interactive: boolean, 0 o 1 (predefinito su 1) se eseguire il comando in modo interattivo. --pageTitle: string page title --template: string (predefinito su "bootstrap") template da utilizzare per il rendering
Per generare la mia documentazione API, di cui è anche la directory api, Farò il seguente:
$ ./vendor/bin/apidoc api api api / web / docs --pageTitle = La TargetDirectory di MeetingPlanner esiste già. Sovrascrivere? (sì | no) [si]: sì Ricerca file da elaborare ... completato. Caricamento dei dati APIDOC dalla cache ... terminato. Controllo dei file aggiornati ... fatto. 8 file da aggiornare. Elaborazione di file ... completata. Aggiornamento di riferimenti incrociati e collegamenti a ritroso ... fatto. Rendering di file: fatto. generare file di indice di estensione ... fatto. generazione dell'indice di ricerca ... fatto. 35 errori sono stati registrati su api / web / docs / errors.txt 214 avvisi sono stati registrati su api / web / docs / warnings.txt
Perché non ho finito di commentare l'intero albero, ci sono errori e avvisi generati. Molto spesso assomigliano a qualcosa del genere:
Array ([0] => Array ([line] => 31 [file] => api / controller / ParticipantController.php [messaggio] => I comportamenti del metodo non hanno genitori da ereditare da in api \ controller \ ParticipantController.) [1 ] => Array ([line] => 32 [file] => api / controller / PlaceController.php [messaggio] => I comportamenti del metodo non hanno genitori da ereditare da in api \ controller \ PlaceController.)
Navigando nella documentazione
Pubblicare la documentazione nella riga di comando apidoc sopra a / API / web / docs significa che puoi consultare la documentazione di Meeting Planner dal web.
Ad esempio, ecco UserTokenController:
Ecco il metodo actionRegister () che mostra i commenti dei parametri riflessi con nell'intestazione informazione.
Ecco la documentazione di MeetingController:
E, ecco il metodo actionMeetingplacechoices ():
Come puoi vedere, questo è estremamente utile per condividere un'API con programmatori di terze parti in tempo reale mentre invii il codice. Il grande vantaggio è che elimina la necessità di mantenere manualmente la documentazione API separatamente.
Ogni volta che puoi eliminare un compito per una startup, è una grande vittoria.
Guardando avanti
Spero che tu abbia visto un po 'del potere dell'estensione dell'apidoc di Yii2. Puoi usarlo per conservare la documentazione per tutto il tuo codice, e inoltre ti incoraggia a tenere il passo con i commenti, che farò più ora.
Se avete domande o feedback, per favore pubblicateli nei commenti. Se desideri tenere il passo con il mio futuro Envato Tuts + tutorial e altre serie, visita la pagina del mio istruttore o segui @reifman. Sicuramente controlla le mie serie di startup e Meeting Planner.
Link correlati
Documento API Yii2 (GitHub)
Programmazione con Yii2: creazione di un'API RESTful (Envato Tuts +)
Costruire la tua startup con PHP: costruire un'API RESTful (Envato Tuts +)
Share
Cosa starai creando
Accentsconagua
