In deze Programmeren met de Yii2-serie, Ik leid lezers in gebruik van het Yii2 Framework voor PHP. Mogelijk bent u ook geïnteresseerd in mijn Introductie tot het Yii Framework, die de voordelen van Yii beoordeelt en een overzicht bevat van wat er nieuw is in Yii 2.x.
Welkom! Onlangs schreef ik over het bouwen van REST-API's voor uw Yii-toepassing en het uitbreiden van aangepaste API's voor onze start-up-serietoepassing, Meeting Planner.
In de tutorial van vandaag zal ik je voorstellen aan de apidoc-extensie van Yii, die automatisch doorzoekbare documentatie voor je code genereert. Ik ga het gebruiken om API-documentatie voor Meeting Planner te genereren.
Ermee beginnen
Het installeren van apidoc is eenvoudig. Zoals hierboven weergegeven, voegt u het pakket gewoon toe met behulp van composer.
Naast het genereren van documentatie van code, is het ook in staat om documentatie van markdown te genereren en dit in pdf's om te zetten.
Er is bijvoorbeeld Yii Framework-documentatie, typische codedocumentatie:
En, hier is de Yii2 Guide, die volgens mij hier wordt gegenereerd door markdown en is geïntegreerd met de codedocumentatie om gemakkelijk te kunnen browsen:
Hier is de documentsyntaxis die apidoc ondersteunt; het is gebaseerd op phpdoc.
Ironisch genoeg is de documentatie voor apidoc nog niet voltooid, maar het is vrij eenvoudig te gebruiken voor elementaire automatische documentatie.
API-documentatie genereren
Als je mijn opstartreeks hebt gevolgd, weet je dat ik een uitgebreide API bouw om mobiele apps te ondersteunen, enz. Apidoc is de ideale manier voor mij om dynamische geautomatiseerde documentatie te onderhouden.
Er zijn zeker veel andere webservices die u helpen uw API te documenteren, maar ik vond dat de apidoc van Yii goed werkte voor mijn behoeften, en ik waardeerde het phpdoc-stijlthema dat zij gebruiken.
Door een standaardcommentaarstijl te gebruiken, is het waarschijnlijk dat andere services eenvoudig documentatie kunnen bouwen vanuit de Meeting Planner-code als ik ze ooit zou willen gebruiken.
Opmerkingenblokken maken
In principe maakt u opmerkingen binnen uw code die door apidoc worden gebruikt om uw documentatie samen te stellen. Het wordt beschreven in de Yii-gids voor codeerstijlen.
U plaatst een opmerkingenblok bovenaan elk bestand zoals deze:
En u plaatst een commentaarblok boven elke controller of modeldefinitie:
/ ** * UserTokenController biedt API-functionaliteit voor registratie, verwijderen en verifiëren * * @author Jeff Reifman * @since 0.1 * / class UserTokenController breidt Controller uit
Vervolgens plaatst u een blok met gedetailleerde opmerkingen boven elke methode, met parameters, retourwaarden en uitzonderingen:
/ ** * Registreer een nieuwe gebruiker met een externe sociale Oauth_token * * @param string $ handtekening de hash gegenereerd met app_secret * @param string $ app_id in header, de gedeelde geheime applicatie id * @param string $ email in header, email adres * @param string $ voornaam in header, voornaam * @param string $ achternaam in header, achternaam * @param string $ oauth_token in header, het token terug van Facebook tijdens OAuth voor deze gebruiker * @param string $ source in header, de bron die het $ oauth_token is van bijvoorbeeld 'facebook' b.v. [$ oauth_token] * @return obj $ identityObj met user_id en user_token * @throws Uitzondering nog niet geïmplementeerd * / public function actionRegister ($ signature, $ app_id = ", $ email =", $ firstname = ", $ lastname =", $ oauth_token = ", $ source =")
U moet de voorgeschreven lay-out volgen zoals beschreven om apidoc met succes te voeden.
Tijdelijke argumenten gebruiken voor API-documentatie
Het Yii-team heeft een apidoc ontwikkeld om codedocumentatie te genereren. Echter, zoals ik al schreef over het beveiligen van uw API, is alles behalve het hash-ondertekeningsargument verplaatst naar http-headers. Deze zijn onzichtbaar voor apidoc. Om API-documentatie te genereren, heb ik besloten om een tijdelijke oplossing te gebruiken.
Zoals je ziet, neem ik dummy-argumenten op in de methoden en specificeer vervolgens in de opmerkingen dat deze als headers of "in header" worden verzonden.
* @param string $ signatuur de hash gegenereerd met app_secret * @param string $ app_id in header, de gedeelde geheime applicatie id * @param string $ email in header, email adres * @param string $ voornaam in header, voornaam * @param string $ achternaam in kop, achternaam
Zolang standaardwaarden zijn opgenomen in de functiedefinities, is er geen echt kwaad gedaan:
U zult in een oogwenk zien hoe dit in het algemeen werkt voor API-documentatie, zelfs als dit niet de optimale codeerstijl is.
Laten we verder gaan met het daadwerkelijk gebruiken van apidoc om de documentatie te genereren.
De documentatie genereren
U kunt apidoc-opdrachten bekijken door het zonder argumenten uit te voeren:
$ ./vendor/bin/apidoc Dit is Yii versie 2.0.10. De volgende opdrachten zijn beschikbaar: - api Genereer klasse API-documentatie. api / index (standaard) API-documentatiebestanden renders - gids Deze opdracht kan documentatie die is opgeslagen als afbeeldingsbestanden, zoals de gids / index van yii, weergeven (standaard) API-documentatiebestanden roderen - help Biedt helpinformatie over console-opdrachten. help / index (standaard) Geeft beschikbare opdrachten of de gedetailleerde informatie weer Om de hulp van elke opdracht te zien, voert u in: apidoc help
Ik gebruik de api-optie, en hier zijn de configuraties die u kunt maken:
$ ./vendor/bin/apidoc help api DESCRIPTION Renders API documentation documentation GEBRUIK US apidoc api [... opties ...] - sourceDirs (vereist): array $ sourceDirs - targetDir (vereist): string $ targetDir OPTIONS --appconfig: tekenreeks aangepast toepassingsconfiguratiebestand pad. Als dit niet wordt ingesteld, wordt de standaardconfiguratie van de toepassing gebruikt. --color: boolean, 0 of 1 om ANSI-kleur in de uitvoer in te schakelen. Als dit niet is ingesteld, wordt ANSI-kleur alleen ingeschakeld voor terminals die dit ondersteunen. --exclude: string | array-bestanden om uit te sluiten. --guide: string url naar waar de gidsbestanden zich bevinden --guidePrefix: string (standaard ingesteld op 'guide-') voorvoegsel om aan alle gidsbestandsnamen toe te voegen. --help, -h: boolean, 0 of 1 om helpinformatie over de huidige opdracht weer te geven. --interactive: boolean, 0 or 1 (standaard 1) of de opdracht interactief moet worden uitgevoerd. --pageTitle: string page title --template: string (standaard naar 'bootstrap') sjabloon om te gebruiken voor rendering
Om mijn API-documentatie te genereren, waarvan de map ook is api, Ik doe het volgende:
$ ./vendor/bin/apidoc api api api / web / docs --pageTitle = MeetingPlanner TargetDirectory bestaat al. Overschrijven? (ja | nee) [ja]: ja Zoeken naar bestanden om te verwerken ... klaar. Apidoc-gegevens laden uit cache ... gereed. Controleren op bijgewerkte bestanden ... klaar. 8 bestanden om te updaten. Bestanden verwerken ... klaar. Bijwerken van verwijzingen en backlinks ... klaar. Bestanden weergeven: voltooid. het genereren van extensie-indexbestanden ... klaar. zoekindex genereren ... klaar. 35 fouten zijn vastgelegd in api / web / docs / errors.txt 214 waarschuwingen zijn vastgelegd in api / web / docs / warnings.txt
Omdat ik nog niet klaar ben met het becommentariëren van de hele boomstructuur, worden er fouten en waarschuwingen gegenereerd. Ze zien er meestal zo uit:
Array ([0] => Array ([regel] => 31 [bestand] => api / controllers / ParticipantController.php [message] => Methodegedragingen mogen geen bovenliggende eigenschap hebben in api \ controllers \ ParticipantController.) [1 ] => Array ([regel] => 32 [bestand] => api / controllers / PlaceController.php [message] => Methoden van gedrag hebben geen bovenliggende eigenschap van in api \ controllers \ PlaceController.)
Bladeren door de documentatie
Publiceren van de documentatie in de bovenstaande opdrachtregel van apidoc naar / Api / web / docs betekent dat u de documentatie van de Meeting Planner kunt bekijken op internet.
Hier is bijvoorbeeld de UserTokenController:
Hier is de actionRegister () -methode die de parametercommentaar weergeeft die wordt weerspiegeld met de in de kop informatie.
Dit is de MeetingController-documentatie:
En, hier is de methode actioneetplaceplacechoices ():
Zoals u kunt zien, is dit uitermate handig om een API met externe programmeurs in realtime te delen terwijl u de code aanlevert. Het grote voordeel is dat het de noodzaak om API-documentatie handmatig apart te beheren overbodig maakt.
Elke keer dat u een taak voor een startup kunt elimineren, is het een enorme overwinning.
Vooruit kijken
Ik hoop dat je een beetje van de kracht van Yii2's apidoc-extensie hebt gezien. Je kunt het gebruiken om documentatie voor al je code bij te houden, en het moedigt je ook aan om commentaar bij te houden, wat ik nu meer zal doen.
Als je vragen of feedback hebt, plaats deze dan in de comments. Als je graag mijn toekomstige Envato Tuts + tutorials en andere series wilt volgen, ga dan naar mijn instructeurspagina of volg @reifman. Bekijk zeker mijn opstartserie en Meeting Planner.
Gerelateerde Links
Yii2 API Doc (GitHub)
Programmeren met Yii2: een RESTful API bouwen (Envato Tuts +)
Bouw je Startup met PHP: Bouw een RESTful API (Envato Tuts +)
Share
Wat je gaat creëren
Accentsconagua
