In acest Programare cu seria Yii2, Îi conduc cititorii în folosirea cadrului Yii2 pentru PHP. Ați putea fi, de asemenea, interesat de mine Introducere în Cadrul Yii, care examinează beneficiile Yii și include o prezentare generală a ceea ce este nou în Yii 2.x.
Bine ati venit! Recent, am scris despre construirea API-urilor REST pentru aplicația dvs. Yii și a extins API-uri personalizate pentru aplicația seria de pornire, Planificatorul întâlnirilor.
În tutorialul de astăzi, vă prezint extensia apidoc a lui Yii, care generează în mod automat o documentație rambursabilă pentru codul dvs. O să o folosesc pentru a genera documentația API pentru Planificatorul de întâlniri.
Noțiuni de bază
Instalarea apidocului este ușoară. Așa cum am arătat mai sus, adăugați doar pachetul folosind compozitorul.
În plus față de generarea de documentație din cod, este capabil, de asemenea, să genereze documentația de la markdown și transformarea acesteia în PDF-uri.
De exemplu, există documentația cadru Yii, documentația tipică a codului:
Și aici este Ghidul Yii2, despre care cred că este generat de marcajul aici și integrat cu documentația codului pentru o navigare ușoară:
Iată sintaxa de documentare pe care apidoc o acceptă; se bazează pe phpdoc.
În mod ironic, documentația pentru apidoc nu este încă completă, dar este destul de ușor de utilizat pentru auto-documentația de bază.
Generarea documentației API
Dacă ați urmat împreună cu seria de pornire, știți că construiesc un API extensiv pentru a sprijini aplicațiile mobile etc. Apidoc este modalitatea ideală pentru mine să păstrez o documentație automată dinamică pentru aceasta.
Desigur, există o mulțime de alte servicii web care vă ajută să vă documentați API-ul, însă am constatat că apidocul lui Yii a funcționat bine pentru nevoile mele și am apreciat tema stilului phpdoc pe care îl folosesc.
Folosind un stil de comentare standard, este probabil ca alte servicii să poată construi cu ușurință documentația din Codul Planificatorului de Întâlniri dacă aș dori să le folosesc.
Crearea blocurilor de comentarii
Practic, creați comentarii în cadrul codului pe care apidoc le utilizează pentru a vă construi documentația. Este descris în ghidul stilului de codare Yii.
Plasați un bloc de comentarii în partea de sus a fiecărui fișier, ca acesta:
Și plasați un bloc de comentarii deasupra fiecărui regulator sau definiție a modelului:
/ ** * UserTokenController oferă funcționalitate API pentru înregistrare, ștergere și verificare * * @author Jeff Reifman * @ din 0.1 * / class UserTokenController extinde Controller
Apoi, plasați un bloc de comentarii detaliat deasupra fiecărei metode, care include parametrii, valorile returnate și excepțiile:
/ ** * Inregistreaza un utilizator nou cu un Oauth_token social extern * * @param string $ semnul hash-ului generat cu app_secret * @param string $ app_id in antet, id-ul aplicatiei secrete partajate * @param string $ email in header, adresa de e-mail * @param string $ firstname in header, first name * @param string $ nume in header, nume * @param string $ oauth_token in antet, token returnat de pe Facebook in timpul OAuth pentru acest utilizator * @param string $ source in header, sursa că $ oauth_token este de ex "facebook" de ex. [$ oauth_token] * @return obj $ identitateObj cu user_id și user_token * @throws Excepție care nu a fost încă implementată * / public action actionRegister ($ signature, $ app_id = ", $ email =", $ firstname = ", $ lastname = $ oauth_token = ", $ source =")
Trebuie să urmați aspectul prescris așa cum este descris pentru a alimenta cu succes apidoc.
Folosirea argumentelor potrivite pentru documentația API
Echipa Yii a dezvoltat apidoc pentru a genera documentația codului. Cu toate acestea, așa cum am scris despre securizarea API-ului dvs., toate argumentele de tip hash signature au fost mutate în anteturile http. Acestea sunt invizibile pentru apidoc. Astfel, pentru a genera documentația API, am decis să folosesc o soluție.
După cum puteți vedea, includem argumente false în metode și apoi specificați în comentarii că acestea sunt trimise ca antete sau "în header".
@ @ param string $ semnătura hash-ul generat cu app_secret * @param string $ app_id în antet, id-ul secret al aplicației partajate * @param string $ email în header, adresa de e-mail * @param string $ firstname în header, first name * @param șirul nume de șir în antet, numele de familie
Atâta timp cât valorile implicite sunt incluse în definițiile funcțiilor, nu există nici un rău real făcut:
Într-o clipă, veți vedea cum funcționează în general documentația API, chiar dacă nu este un stil de codare optim.
Să mergem la utilizarea de fapt a apidoc pentru a genera documentația.
Generarea documentației
Puteți examina comenzile apidoc rulând fără argumente:
$ ./vendor/bin/apidoc Aceasta este versiunea Yii 2.0.10. Sunt disponibile următoarele comenzi: - api Generarea documentației API de clasă. api / index (implicit) Renders fișiere de documentare API - ghid Această comandă poate face ca documentația să fie stocată ca fișiere de marcare, cum ar fi ghidul / indicele de ghidare yii (implicit) Renders API fișierele de documentație - ajutor Oferă informații de ajutor despre comenzile consolei. help / index (implicit) Afișează comenzile disponibile sau informațiile detaliate Pentru a vedea ajutorul fiecărei comenzi, introduceți: help apidoc
Voi folosi opțiunea api și aici sunt configurațiile pe care le puteți face:
$ ./vendor/bin/apidoc help api DESCRIERE Renders fisiere documentatie API UTILIZARE apidoc api [... opțiuni ...] - sourceDirs (necesar): array $ sourceDirs - targetDir (obligatoriu): string $ targetDir OPTIONS --appconfig: Dacă nu este setat, se utilizează configurația implicită a aplicației. --color: boolean, 0 sau 1 dacă se activează culoarea ANSI în ieșire. Dacă nu este setat, culoarea ANSI va fi activată numai pentru terminalele care o acceptă. - excludeți: șirul | fișierele array pentru a exclude. --guide: url șir la locația unde sunt localizate fișierele ghidului --guidePrefix: string (implicit la "ghid") pentru a prefixa la toate numele de fișiere ghidate. --help, -h: boolean, 0 sau 1 pentru a afișa informații de ajutor despre comanda curentă. - interactiv: boolean, 0 sau 1 (implicit la 1) dacă să rulați comanda interactiv. --pageTitle: titlul paginii șir - template: string (implicit la "bootstrap") șablon de utilizat pentru redare
Pentru a genera documentația mea API, al cărei director este, de asemenea api, Voi face următoarele:
$ ./vendor/bin/apidoc api api api / web / docs --pageTitle = Setul MeetingPlanner TargetDirectory există deja. Suprascrieți? (da | nu) [da]: da Căutarea fișierelor de procesat ... terminat. Se încarcă datele apidoc din cache ... terminat. Se verifică fișierele actualizate ... terminate. 8 fișiere pentru a fi actualizate. Procesarea fișierelor ... terminat. Actualizarea referințelor încrucișate și a backlink-urilor ... terminate. Raportarea fișierelor: terminat. generarea de fișiere index de extensie ... făcut. generând indexul de căutare ... făcut. 35 de erori au fost înregistrate în api / web / docs / errors.txt Avertizările 214 au fost înregistrate în api / web / docs / warnings.txt
Pentru că nu am terminat să comentez întregul copac, sunt generate erori și avertismente. Cel mai adesea arata cam asa:
Array ([0] => Array ([line] => 31 [file] => api / controllers / ParticipantController.php [message] => ] => Array ([line] => 32 [file] => api / controllers / PlaceController.php [message] => Comportamentul metodei nu are moștenire de la api \ controllers \ PlaceController.
Navigarea în documentație
Publicarea documentației din linia de comandă apidoc de mai sus / api / web / docs înseamnă că puteți să răsfoiți documentația Meeting Planner de pe web.
De exemplu, aici este UserTokenController:
Aici este metoda actionRegister () care afișează comentariile parametrilor reflectate cu în antet informație.
Iată documentația MeetingController:
Și, aici este metoda actionMeetingplacechoices ():
După cum puteți vedea, acest lucru este extrem de util pentru partajarea unui API cu programatori de la terți în timp real pe măsură ce livrați codul. Marele beneficiu este că elimină necesitatea de a menține manual documentația API separat.
Oricând puteți elimina o sarcină pentru o pornire, este o victorie uriașă.
Privind înainte
Sper că ați văzut puțină putere din extensia apidocului lui Yii2. Puteți să-l utilizați pentru a păstra documentația pentru întregul cod și, de asemenea, vă încurajează să țineți pasul cu comentariile, pe care le voi face acum.
Dacă aveți întrebări sau feedback, vă rugăm să le postați în comentarii. Dacă doriți să continuați cu viitoarele tutoriale Envato Tuts + și alte serii, vă rugăm să vizitați pagina mea de instructor sau să urmați @reifman. În mod sigur, verificați seria de pornire și Planificatorul de întâlniri.
Link-uri conexe
Documentul API Yii2 (GitHub)
Programarea cu Yii2: Construirea unui API RESTful (Envato Tuts +)
Construirea sistemului de pornire cu PHP: Construirea unui API RESTful (Envato Tuts +)
Share
Ce veți crea
Accentsconagua
