Mit Yii programmieren Dokumentation erstellen

Was Sie erstellen werden

In diesem Programmierung mit der Yii2-Serie, Ich unterstütze die Leser beim Einsatz des Yii2-Frameworks für PHP. Sie könnten auch an meinem interessiert sein Einführung in das Yii-Framework, Hier werden die Vorteile von Yii erläutert und eine Übersicht über die Neuerungen in Yii 2.x gegeben.

Herzlich willkommen! Vor kurzem habe ich über das Erstellen von REST-APIs für Ihre Yii-Anwendung berichtet und benutzerdefinierte APIs für unsere Startserienanwendung Meeting Planner erweitert.

Im heutigen Tutorial werde ich Ihnen die Apidi-Erweiterung von Yii vorstellen, die automatisch durchsuchbare Dokumentation für Ihren Code generiert. Ich werde es verwenden, um API-Dokumentation für Meeting Planner zu generieren.

Fertig machen

Apidoc zu installieren ist einfach. Wie oben gezeigt, fügen Sie das Paket einfach mit Composer hinzu.

Neben der Generierung von Dokumentation aus Code kann auch Dokumentation aus Markdown generiert und in PDF-Dateien umgewandelt werden.

Zum Beispiel gibt es eine Yii Framework-Dokumentation, eine typische Codedokumentation:

Und hier ist der Yii2 Guide, von dem ich glaube, dass er hier von Markdown generiert wird und in die Codedokumentation integriert ist, um das Browsen zu erleichtern:

Hier ist die Dokumentation, die Apidoc unterstützt. es basiert auf phpdoc.

Ironischerweise ist die Dokumentation für Apidoc noch nicht vollständig, aber für die einfache Autodokumentation ist es relativ einfach.

API-Dokumentation generieren

Wenn Sie die Startserie mitverfolgt haben, wissen Sie, dass ich eine umfangreiche API zur Unterstützung von mobilen Apps usw. entwickle. Apidoc ist die ideale Methode, um eine dynamische, automatisierte Dokumentation für sie zu erstellen.

Sicherlich gibt es viele andere Web-Services, die Ihnen helfen, Ihre API zu dokumentieren, aber ich fand heraus, dass Yiis Apidoc für meine Bedürfnisse gut funktionierte, und ich schätzte das von ihnen verwendete phpdoc-Design.

Die Verwendung eines Standardkommentierungsstils macht es wahrscheinlich, dass andere Dienste leicht Dokumentation aus Meeting Planner-Code erstellen können, wenn ich sie jemals verwenden möchte.

Kommentarblöcke erstellen

Grundsätzlich erstellen Sie Kommentare in Ihrem Code, die von apidoc zum Erstellen Ihrer Dokumentation verwendet werden. Es wird in der Yii-Codierungsstil-Anleitung beschrieben.

Sie platzieren einen Kommentarblock am Anfang jeder Datei wie diesen:

Und Sie platzieren einen Kommentarblock über jeder Steuerung oder Modelldefinition:

/ ** * UserTokenController bietet API-Funktionen zum Registrieren, Löschen und Überprüfen von * * @author Jeff Reifman  * @since 0.1 * / class UserTokenController erweitert Controller

Dann platzieren Sie einen detaillierten Kommentarblock über jeder Methode, der Parameter, Rückgabewerte und Ausnahmen enthält:

/ ** * Registrieren eines neuen Benutzers bei einem externen sozialen Oauth_token * * @param string $ Signatur der mit app_secret * @param string $ app_id im Header generierte Hash, die gemeinsam genutzte geheime Anwendungs-ID * @param string $ email im Header, E-Mail-Adresse * @param string $ firstname im Header, Vorname * @param string $ lastname im Header, Nachname * @param string $ oauth_token im Header, das von Facebook während OAuth für diesen Benutzer zurückgegebene Token * @param string $ source im Header, die Quelle, aus der das $ oauth_token stammt, z "facebook", z. [$ oauth_token] * @return obj $ identityObj mit user_id und user_token * @throws Ausnahme noch nicht implementiert * / public function actionRegister ($ signature, $ app_id = ", $ email =", $ firstname = ", $ lastname =", $ oauth_token = ", $ source =")

Sie müssen dem vorgeschriebenen Layout wie beschrieben folgen, um Apidoc erfolgreich zu füttern.

Verwenden von Platzhalterargumenten für die API-Dokumentation

Das Yii-Team entwickelte Apidoc zur Generierung der Codedokumentation. Wie ich bereits in "Sichern der API" beschrieben habe, wurde alles außer dem Hash-Signaturargument in http-Header verschoben. Diese sind für Apidoc unsichtbar. Um die API-Dokumentation zu generieren, entschied ich mich daher für eine Problemumgehung.

Wie Sie sehen, füge ich Dummy-Argumente in die Methoden ein und lege dann in den Kommentaren fest, dass diese als Header oder "in Header" gesendet werden.

* @param string $ Signatur der mit app_secret generierte Hash * @param string $ app_id im Header, die gemeinsam genutzte geheime Anwendungs-ID * @param string $ email im Header, E-Mail-Adresse * @param string $ Vorname im Header, Vorname * @param Zeichenfolge $ lastname im Header, Nachname

Solange Standardwerte in den Funktionsdefinitionen enthalten sind, gibt es keinen wirklichen Schaden:

öffentliche Funktion actionRegister ($ signature, $ app_id = ", $ email =", $ firstname = ", $ lastname =", $ oauth_token = ", $ source =")

In Kürze werden Sie sehen, wie dies in der Regel für die API-Dokumentation funktioniert, auch wenn dies nicht der optimale Codierstil ist.

Fahren wir mit der eigentlichen Verwendung von Apidoc fort, um die Dokumentation zu generieren.

Dokumentation erstellen

Sie können Apidoc-Befehle überprüfen, indem Sie sie ohne Argumente ausführen:

$ ./vendor/bin/apidoc Dies ist Yii Version 2.0.10. Die folgenden Befehle sind verfügbar: - api Generate class API documentation. api / index (Standard) Rendert API-Dokumentationsdateien - Anleitung Mit diesem Befehl können Sie die als Markdown-Dateien gespeicherte Dokumentation rendern, z. B. yii guide guide / index (Standard). Rendern von API-Dokumentationsdateien - help Enthält Hilfeinformationen zu Konsolenbefehlen. help / index (Standard) Zeigt verfügbare Befehle oder detaillierte Informationen an. Geben Sie Folgendes ein, um die Hilfe jedes Befehls anzuzeigen: apidoc help

Ich verwende die API-Option und hier sind die Konfigurationen, die Sie vornehmen können:

$ ./vendor/bin/apidoc help api BESCHREIBUNG Rendert API-Dokumentationsdateien USAGE apidoc api   [… Options…] - sourceDirs (erforderlich): Array $ sourceDirs - targetDir (erforderlich): string $ targetDir OPTIONS --appconfig: String Pfad der benutzerdefinierten Anwendungskonfigurationsdatei. Wenn nicht festgelegt, wird die Standardanwendungskonfiguration verwendet. --color: boolean, 0 oder 1, um ANSI-Farbe in der Ausgabe zu aktivieren. Wenn nicht festgelegt, wird ANSI-Farbe nur für Terminals aktiviert, die dies unterstützen. --exclude: String | Array-Dateien, die ausgeschlossen werden sollen. --guide: string URL zu dem Ort, an dem sich die Guide-Dateien befinden --guidePrefix: string (standardmäßig "guide-"), um alle Namen der Guide-Dateien voranzustellen. --help, -h: boolean, 0 oder 1, um Hilfeinformationen zum aktuellen Befehl anzuzeigen. --interactive: boolean, 0 oder 1 (Standardeinstellung 1), um den Befehl interaktiv auszuführen. --pageTitle: string Seitentitel --template: string (Standardeinstellung ist "bootstrap") Vorlage, die für das Rendern verwendet wird

Um meine API-Dokumentation zu generieren, deren Verzeichnis ebenfalls ist api, Ich mache folgendes:

$ ./vendor/bin/apidoc api api api / web / docs --pageTitle = MeetingPlanner TargetDirectory ist bereits vorhanden. Überschreiben? (ja | nein) [ja]: ja Dateien werden gesucht ... fertig. Apidoc-Daten aus dem Cache laden… fertig. Nach aktualisierten Dateien suchen… fertig. 8 zu aktualisierende Dateien. Dateien werden verarbeitet ... fertig. Querverweise und Backlinks aktualisieren… fertig. Dateien rendern: fertig. Erzeugen von Erweiterungsindexdateien… fertig. Suchindex generieren… fertig. 35 Fehler wurden in api / web / docs / errors.txt protokolliert. 214 Warnungen wurden in api / web / docs / warnings.txt protokolliert

Da ich den gesamten Baum noch nicht kommentiert habe, werden Fehler und Warnungen generiert. Sie sehen meistens so aus:

Array ([0] => Array ([line] => 31 [file] => api / controller / ParticipantController.php [message] => Das Verhalten der Methode hat kein übergeordnetes Element, das in "api \ controller \ ParticipantController" geerbt werden kann.) [1 ] => Array ([Zeile] => 32 [Datei] => API / Controller / PlaceController.php [Nachricht] => Das Verhalten der Methode hat kein übergeordnetes Element, das in "API \ Controller \ PlaceController" erben kann.)

Durchsuchen der Dokumentation

Veröffentlichen Sie die Dokumentation in der obigen apidoc-Befehlszeile unter / api / web / docs bedeutet, dass Sie die Meeting Planner-Dokumentation vom Internet aus durchsuchen können.

Hier ist zum Beispiel der UserTokenController:

Hier ist die actionRegister () -Methode, die die Parameterkommentare zeigt, die mit der reflektiert werden im Header Information.

Hier ist die MeetingController-Dokumentation:

Und hier ist die actionMeetingplacechoices () -Methode:

Wie Sie sehen, ist dies äußerst nützlich, wenn Sie eine API in Echtzeit mit Programmierern von Drittanbietern teilen möchten, während Sie den Code bereitstellen. Der große Vorteil ist, dass die API-Dokumentation nicht separat manuell verwaltet werden muss.

Immer wenn Sie eine Aufgabe für ein Startup eliminieren können, ist dies ein großer Gewinn.

Vorausschauen

Ich hoffe, dass Sie ein bisschen von der Stärke der Apidoc-Erweiterung von Yii2 gesehen haben. Sie können es verwenden, um die Dokumentation für Ihren gesamten Code aufzubewahren, und ermutigt Sie außerdem dazu, mit den Kommentaren auf dem Laufenden zu bleiben, die ich jetzt noch ausführen werde.

Wenn Sie Fragen oder Anregungen haben, schreiben Sie diese bitte in die Kommentare. Wenn Sie mit meinen zukünftigen Envato Tuts + -Tutorials und anderen Serien mithalten möchten, besuchen Sie bitte meine Instructor-Seite oder folgen Sie @reifman. Schauen Sie sich unbedingt meine Startserie und den Meeting Planner an.