I denna Programmering med Yii2-serien, Jag vägledande läsare som använder Yii2 Framework for PHP. Du kanske också är intresserad av mina Introduktion till Yii Framework, som granskar fördelarna med Yii och innehåller en översikt över vad som är nytt i Yii 2.x.
Välkommen! Nyligen skrev jag om att bygga REST API för din Yii-applikation och utökade anpassade API för vår startprogramserie, mötesplanerare.
I dagens handledning introducerar jag dig till Yiis apidoc-förlängning, som automatiskt genererar bläddrad dokumentation för din kod. Jag ska använda den för att skapa API-dokumentation för mötesplaneraren.
Komma igång
Installera apidoc är enkelt. Som visas ovan lägger du bara till paketet med kompositör.
Förutom att generera dokumentation från kod, kan den också skapa dokumentation från markdown och omvandla den till PDF-filer.
Det finns till exempel Yii Framework dokumentation, typisk koddokumentation:
Och här är Yii2 Guide, som jag tror genereras av markdown här och integrerad med koddokumentationen för enkel surfning:
Här är dokumentationssyntaxen som Apidoc stöder; Det är baserat på phpdoc.
Ironiskt nog är dokumentationen för apidoc ännu inte färdig, men det är ganska lätt att använda för grundläggande automatisk dokumentation.
Genererar API-dokumentation
Om du har följt med min startserie, är du medveten om att jag bygger ett omfattande API för att stödja mobilappar etc. Apidoc är den perfekta sätten för mig att behålla dynamisk automatisk dokumentation för den.
Visst finns det många andra webbtjänster som hjälper dig att dokumentera ditt API, men jag fann att Yii apidoc fungerade bra för mina behov, och jag uppskattade phpdoc-stilen som de använder.
Genom att använda en standardkommentareringsstil gör det troligt att andra tjänster kan enkelt bygga dokumentation från mötesplannerkoden om jag någonsin vill använda dem.
Skapa kommentarblock
I grund och botten skapar du kommentarer inom din kod som apidoc använder för att bygga din dokumentation. Den beskrivs i Yii-kodningsstilvägledningen.
Du lägger ett kommentarblock högst upp i varje fil som den här:
Och du lägger ett kommentarblock ovanför varje kontroller eller modelldefinition:
/ ** * UserTokenController tillhandahåller API-funktionalitet för registrering, radering och verifiering * * @ author Jeff Reifman * @since 0.1 * / class UserTokenController utökar Controller
Sedan lägger du ett detaljerat kommentarblock ovanför varje metod, som innehåller parametrar, returvärden och undantag:
/ ** * Registrera en ny användare med en extern social Oauth_token * * @param-sträng $ signatur hash som genereras med app_secret * @param string $ app_id i huvudet, det delade hemliga ansöknings-id * @param string $ email i header, e-postadress * @paramsträng $ förnamn i rubrik, förnamn * @paramsträng $ efternamn i rubrik, efternamn * @paramsträng $ oauth_token i huvudet, tokenen returneras från Facebook under OAuth för den här användaren * @paramsträng $ kilde i rubrik, källan att $ oauth_token är från t.ex. "facebook" t.ex. [$ oauth_token] * @return obj $ identityObj med user_id och user_token * @throws Undantag ännu inte genomförd * / public function actionRegister ($ signatur, $ app_id = ", $ email =", $ firstname = ", $ lastname =", $ oauth_token = ", $ source =")
Du måste följa den föreskrivna layouten som beskrivs för att mata apidoc framgångsrikt.
Använda platshållargument för API-dokumentation
Yii-teamet utvecklade apidoc för att generera koddokumentation. Men som jag skrev om att säkra ditt API har allt utom hash-signatur-argumentet flyttats till http-rubriker. Dessa är osynliga för apidoc. Således, för att generera API-dokumentation, bestämde jag mig för att använda en lösning.
Som du kan se innehåller jag dummyargument i metoderna och anger sedan i kommentarerna att dessa skickas som rubriker eller "i rubrik".
* @paramsträng $ signatur hash som genereras med app_secret * @paramsträng $ app_id i header, den delade hemliga ansöknings-iden * @param-strängen $ email i rubrik, e-postadress * @paramsträng $ förnamn i rubrik, förnamn * @param sträng $ efternamn i rubrik, efternamn
Så länge som standardvärden ingår i funktionsdefinitionerna är det ingen riktig skada som görs:
I ett ögonblick ser du hur det generellt fungerar för API-dokumentation, även om det inte är en optimal kodningsstil.
Låt oss fortsätta att faktiskt använda apidoc för att generera dokumentationen.
Generera dokumentationen
Du kan granska apidoc kommandon genom att köra den utan argument:
$ ./vendor/bin/apidoc Detta är Yii version 2.0.10. Följande kommandon är tillgängliga: - api Generera klass API-dokumentation. api / index (standard) Renders API-dokumentationsfiler - guide Det här kommandot kan göra dokumentation lagrad som markdown-filer som yii guide / index (standard) Renders API-dokumentationsfiler - hjälp Ger hjälpinformation om konsolkommandon. hjälp / index (standard) Visar tillgängliga kommandon eller den detaljerade informationen För att se hjälp av varje kommando, ange: apidoc help
Jag använder api-alternativet, och här är konfigurationerna du kan göra:
$ ./vendor/bin/apidoc help api BESKRIVNING Renders API dokumentationsfiler USAGE apidoc api [... alternativ ...] - sourceDirs (krävs): array $ sourceDirs - targetDir (krävs): sträng $ targetDir OPTIONS --appconfig: sträng anpassad programkonfigurationsfilväg. Om den inte är inställd används standardprogramkonfiguration. --färg: booleskt, 0 eller 1 om du vill aktivera ANSI-färg i utgången. Om den inte är inställd, kommer ANSI-färg endast att aktiveras för terminaler som stöder den. --exkludera: sträng | array-filer att utesluta. --guide: strängadress till var guidefilerna är placerade - guidePrefix: sträng (standardvärden till "guide") prefix för att förordnas till alla guiden filnamn. --hjälp, -h: booleskt, 0 eller 1 om du vill visa hjälpinformation om aktuellt kommando. --interaktiv: booleska, 0 eller 1 (standard till 1) om kommandot ska fungera interaktivt. --pageTitle: strängsidettitel --template: sträng (standard till "bootstrap") mall som ska användas för rendering
För att generera min API dokumentation, vars katalog också är api, Jag gör följande:
$ ./vendor/bin/apidoc api api api / web / docs --pageTitle = MeetingPlanner TargetDirectory finns redan. Skriva över? (ja | nej) [ja]: ja Söker filer att bearbeta ... gjort. Laddar apidoc data från cache ... gjort. Kontrollera efter uppdaterade filer ... gjort. 8 filer att uppdatera. Bearbetning av filer ... gjort. Uppdatering av korsreferenser och bakåtlänkar ... gjort. Rendering av filer: gjort. genererar förlängningsindexfiler ... gjort. genererar sökindex ... gjort. 35 fel har loggats till api / web / docs / errors.txt 214 varningar har loggats till api / web / docs / warnings.txt
Eftersom jag inte har kommit igenom hela trädet finns det fel och varningar som genereras. De ser oftast ut så här:
Array ([0] => Array ([line] => 31 [file] => api / controllers / ParticipantController.php [message] => Metodsbeteenden har ingen förälder att arva från i api \ controllers \ ParticipantController. ] => Array ([line] => 32 [file] => api / controllers / PlaceController.php [message] => Metodsbeteenden har ingen förälder att arva från i api \ controllers \ PlaceController.)
Bläddrar i dokumentationen
Publicering av dokumentationen i ovanstående apidoc kommandorad till / api / webb / docs innebär att du kan bläddra i mötesplaneringsdokumentationen från webben.
Till exempel, här är UserTokenController:
Här är metoden actionRegister () som visar de parameterventarier som återspeglas med i huvudet information.
Här är MeetingController-dokumentationen:
Och här är metoden actionMeetingplacechoices ():
Som du kan se är det väldigt användbart för att dela ett API med tredjepartsprogrammerare i realtid när du levererar koden. Den stora fördelen är att det eliminerar behovet av att manuellt upprätthålla API-dokumentationen separat.
När som helst kan du eliminera en uppgift för en start, det är en stor vinst.
Blickar framåt
Jag hoppas att du har sett lite av kraften i Yii2s apidoc-förlängning. Du kan använda den för att behålla dokumentationen för hela din kod, och det uppmuntrar dig också att följa med kommentarer, vilket jag gör mer av nu.
Om du har några frågor eller kommentarer, vänligen skicka in dem i kommentarerna. Om du vill hålla koll på mina framtida Envato Tuts + handledning och andra serier, besök min instruktörssida eller följ @reifman. Kolla in min start-serie och mötesplanerare.
relaterade länkar
Yii2 API Doc (GitHub)
Programmering med Yii2: Skapa ett RESTful API (Envato Tuts +)
Bygga din start med PHP: Skapa ett RESTful API (Envato Tuts +)
Share
Vad du ska skapa
Accentsconagua
