I dette Programmering med Yii2-serien, Jeg veileder lesere i bruk av Yii2 Framework for PHP. Du kan også være interessert i min Introduksjon til Yii Framework, som vurderer fordelene med Yii og inneholder en oversikt over hva som er nytt i Yii 2.x.
Velkommen! Nylig skrev jeg om å bygge REST APIer for Yii-applikasjonen og utvidede egendefinerte APIer for vår oppstartsserieapplikasjon, Meeting Planner.
I dagens veiledning vil jeg introdusere deg til Yiis apidoc-utvidelse, som automatisk genererer brukbar dokumentasjon for koden din. Jeg skal bruke den til å generere API dokumentasjon for Meeting Planner.
Starter
Det er enkelt å installere apidoc. Som vist ovenfor, legger du bare til pakken med komponist.
I tillegg til å generere dokumentasjon fra kode, er det også i stand til å generere dokumentasjon fra markdown og omforme dette til PDF-filer.
For eksempel er det Yii Framework dokumentasjon, typisk kode dokumentasjon:
Og her er Yii2 Guide, som jeg tror er generert fra markdown her og integrert med kodedokumentasjonen for enkel surfing:
Her er dokumentasjonssyntaxen som apidoc støtter; den er basert på phpdoc.
Ironisk nok er dokumentasjonen for apidoc ennå ikke fullført, men det er ganske enkelt å bruke for grunnleggende auto-dokumentasjon.
Genererer API-dokumentasjon
Hvis du har fulgt sammen med oppstartsserien, er du klar over at jeg bygger en omfattende API for å støtte mobilapper, etc. Apidoc er den ideelle måten for meg å opprettholde dynamisk automatisk dokumentasjon for det.
Absolutt er det mange andre webtjenester som hjelper deg med å dokumentere API-en din, men jeg fant ut at Yii's apidoc fungerte bra for mine behov, og jeg satte pris på temaet phpdoc-stil de bruker.
Ved å bruke en standard kommentar stil gjør det sannsynlig at andre tjenester vil kunne enkelt bygge dokumentasjon fra Meeting Planner kode hvis jeg noen gang ønsker å bruke dem.
Opprette kommentarblokk
I utgangspunktet lager du kommentarer i koden din som apidoc bruker til å bygge dokumentasjonen din. Den er beskrevet i Yii-kodestilguiden.
Du legger en kommentarblokk øverst på hver fil som denne:
Og du legger en kommentarblokk over hver kontroller eller modelldefinisjon:
/ ** * UserTokenController gir API-funksjonalitet for registrering, slett og verifiser * * @author Jeff Reifman * @Since 0.1 * / klasse UserTokenController utvider kontrolleren
Deretter plasserer du en detaljert kommentarblokk over hver metode, som inkluderer parametere, returverdier og unntak:
/ ** * Registrer en ny bruker med en ekstern sosial Oauth_token * * @param string $ signatur hash generert med app_secret * @param string $ app_id i topptekst, den delte hemmelige søknaden id * @param string $ email i header, e-postadresse * @param string $ firstname i header, fornavn * @param string $ etternavn i header, etternavn * @param string $ oauth_token i topptekst, token returneres fra Facebook under OAuth for denne brukeren * @param string $ source i header, kilden som $ oauth_token er fra f.eks 'facebook' f.eks. [$ oauth_token] * @return obj $ identityObj med user_id og user_token * @throws Unntak ennå ikke implementert * / offentlig funksjon actionRegister ($ signatur, $ app_id = ", $ email =", $ firstname = ", $ lastname =", $ oauth_token = ", $ source =")
Du må følge foreskrevet layout som beskrevet for å kunne levere apidoc vellykket.
Bruke plassholderargumenter for API-dokumentasjon
Yii-teamet utviklet apidoc for å generere kodedokumentasjon. Imidlertid, som jeg skrev om i Sikring av API, har alt annet enn hash signatur-argumentet blitt flyttet til http-overskrifter. Disse er usynlige for apidoc. For å generere API-dokumentasjon bestemte jeg meg for å bruke en løsning.
Som du kan se, inkluderer jeg dummy argumenter i metodene og angir deretter i kommentarene at disse blir sendt som overskrifter eller "i overskrift".
* @param string $ signatur hash generert med app_secret * @param string $ app_id i topptekst, den delte hemmelige søknaden id * @param string $ email i topptekst, e-postadresse * @param string $ fornavn i overskrift, fornavn * @param streng $ etternavn i header, etternavn
Så lenge standardverdier er inkludert i funksjonsdefinisjonene, er det ingen reell skade gjort:
I et øyeblikk ser du hvordan dette generelt fungerer for API-dokumentasjon, selv om det ikke er optimal kodestil.
La oss fortsette å faktisk bruke apidoc til å generere dokumentasjonen.
Generering av dokumentasjonen
Du kan gjennomgå apidoc-kommandoer ved å kjøre den uten argumenter:
$ ./vendor/bin/apidoc Dette er Yii versjon 2.0.10. Følgende kommandoer er tilgjengelige: - api Generer klassens API-dokumentasjon. api / index (standard) Renders API dokumentasjonsfiler - guide Denne kommandoen kan gjøre dokumentasjon lagret som markdownfiler som yii guide guide / index (standard) Renders API dokumentasjonsfiler - hjelp Gir hjelpinformasjon om konsollkommandoer. hjelp / indeks (standard) Viser tilgjengelige kommandoer eller detaljert informasjon For å se hjelpen til hver kommando, skriv inn: apidoc hjelp
Jeg bruker api-alternativet, og her er konfigurasjonene du kan gjøre:
$ ./vendor/bin/apidoc help api BESKRIVELSE Renders API dokumentasjonsfiler USAGE apidoc api [... opsjoner ...] - sourceDirs (obligatorisk): array $ sourceDirs - targetDir (påkrevd): streng $ targetDir OPTIONS --appconfig: streng tilpasset programkonfigurasjonsfilbane. Hvis ikke satt, brukes standard programkonfigurasjon. --farger: boolsk, 0 eller 1 om du vil aktivere ANSI-farge i utgangen. Hvis ikke satt, vil ANSI-farge bare aktiveres for terminaler som støtter det. - ekskluder: streng | array filer for å ekskludere. --guide: streng-URL til hvor styringsfilene er plassert - guidePrefix: streng (standard til 'guide-') prefiks for å prepend til alle guide filnavn. --hjelp, -h: boolsk, 0 eller 1 om du vil vise hjelpinformasjon om gjeldende kommando. --interaktiv: boolsk, 0 eller 1 (standard til 1) om du vil kjøre kommandoen interaktivt. --pageTitle: strengside tittel --template: streng (standard til 'bootstrap') mal som skal brukes til gjengivelse
For å generere API-dokumentasjonen, hvis katalog også er api, Jeg gjør følgende:
$ ./vendor/bin/apidoc api api api / web / docs --pageTitle = MeetingPlanner TargetDirectory eksisterer allerede. Skrive? (ja | nei) [ja]: ja Søker filer å behandle ... ferdig. Laster apidoc data fra cache ... ferdig. Sjekker for oppdaterte filer ... ferdig. 8 filer for å oppdatere. Prosessering av filer ... ferdig. Oppdaterer kryssreferanser og tilbakekoblinger ... ferdig. Gjenopprette filer: ferdig. genererer utvidelsesindeksfiler ... ferdig. genererer søkeindeks ... ferdig. 35 feil har blitt logget til api / web / docs / errors.txt 214 advarsler er logget til api / web / docs / warnings.txt
Fordi jeg ikke er ferdig med å kommentere hele treet, er det generert feil og advarsler. De ser ofte slik ut som:
Array ([0] => Array ([linje] => 31 [fil] => api / controllers / ParticipantController.php [message] => Metodeadferd har ingen forelder å arve fra i api \ controllers \ ParticipantController.) [1 ] => Array ([line] => 32 [file] => api / controllers / PlaceController.php [message] => Metodeadferd har ingen forelder å arve fra i api \ controllers \ PlaceController.)
Bla gjennom dokumentasjonen
Publisering av dokumentasjonen i ovennevnte apidoc kommandolinje til / api / web / docs betyr at du kan bla gjennom møterplanleggerens dokumentasjon fra nettet.
For eksempel, her er UserTokenController:
Her er metoden actionRegister () som viser parameterkommentarene reflektert med i header informasjon.
Her er MeetingController-dokumentasjonen:
Og her er fremgangsmåten actionMeetingplacechoices ():
Som du kan se, er dette ekstremt nyttig for å dele en API med tredjepartsprogrammerere i sanntid når du leverer koden. Den store fordelen er at det eliminerer behovet for å manuelt vedlikeholde API-dokumentasjonen separat.
Når som helst du kan eliminere en oppgave for oppstart, er det en stor seier.
Ser fremover
Jeg håper at du har sett litt av kraften til Yii2s apidoc-forlengelse. Du kan bruke den til å opprettholde dokumentasjonen for hele koden din, og det oppfordrer deg også til å følge opp med kommentarer, som jeg vil gjøre mer av nå.
Hvis du har spørsmål eller tilbakemelding, vennligst legg inn dem i kommentarene. Hvis du vil fortsette med fremtidige Envato Tuts + opplæringsprogrammer og andre serier, vennligst besøk min instruktørside eller følg @reifman. Sjekk sjekk ut min oppstartsserie og møteplanlegger.
Relaterte linker
Yii2 API Doc (GitHub)
Programmering med Yii2: Bygg et RESTful API (Envato Tuts +)
Bygg opp oppstart med PHP: Bygg et RESTful API (Envato Tuts +)
Share
Hva du skal skape
Accentsconagua
