Dans ce Programmation avec la série Yii2, Je guide les lecteurs dans l'utilisation du framework Yii2 pour PHP. Vous pouvez également être intéressé par mon Introduction au framework Yii, qui passe en revue les avantages de Yii et inclut un aperçu des nouveautés de Yii 2.x.
Bienvenue! Récemment, j'ai écrit sur la création d'API REST pour votre application Yii et sur des API personnalisées étendues pour notre application de série de démarrage, Meeting Planner..
Dans le tutoriel d'aujourd'hui, je vais vous présenter l'extension apidoc de Yii, qui génère automatiquement une documentation navigable pour votre code. Je vais l'utiliser pour générer une documentation sur l'API pour Meeting Planner..
Commencer
L'installation d'apidoc est facile. Comme indiqué ci-dessus, vous ajoutez simplement le package à l'aide de composer.
En plus de générer de la documentation à partir de code, il est également capable de générer de la documentation à partir de markdown et de la transformer en PDF..
Par exemple, il y a la documentation Yii Framework, la documentation de code typique:
Et, voici le guide Yii2, qui, je crois, est généré à partir de markdown ici et intégré à la documentation du code pour une navigation aisée:
Voici la syntaxe de documentation prise en charge par apidoc; c'est basé sur phpdoc.
Ironiquement, la documentation pour apidoc n’est pas encore complète, mais elle est assez facile à utiliser pour la documentation automatique de base..
Génération de la documentation API
Si vous avez suivi ma série de startups, vous savez que je construis une API complète pour prendre en charge les applications mobiles, etc. Apidoc est le moyen idéal pour moi de maintenir une documentation automatisée dynamique pour cela..
Certes, il existe de nombreux autres services Web qui vous aident à documenter votre API, mais j’ai trouvé que l’apidoc de Yii fonctionnait bien pour mes besoins et j’ai apprécié le thème de style phpdoc qu’ils utilisent..
En utilisant un style de commentaire standard, il est probable que d'autres services pourront facilement créer de la documentation à partir du code de Meeting Planner si je souhaite les utiliser..
Création de blocs de commentaires
Fondamentalement, vous créez des commentaires dans votre code qu'apidoc utilise pour créer votre documentation. Il est décrit dans le guide de style de codage Yii.
Vous placez un bloc de commentaires en haut de chaque fichier, comme celui-ci:
Et vous placez un bloc de commentaires au-dessus de chaque contrôleur ou définition de modèle:
/ ** * UserTokenController fournit une fonctionnalité API pour l'enregistrement, la suppression et la vérification * * @author Jeff Reifman * @since 0.1 * / class UserTokenController étend Controller
Ensuite, vous placez un bloc de commentaires détaillé au-dessus de chaque méthode, qui inclut des paramètres, des valeurs de retour et des exceptions:
/ ** * Enregistre un nouvel utilisateur avec un réseau social externe Oauth_token * * * @param chaîne $ signature le hachage généré avec app_secret * @param chaîne $ app_id dans l'en-tête, l'identifiant d'application secret partagé * * @param chaîne $ email dans l'en-tête, adresse e-mail * @param chaîne $ prénom dans l'en-tête, prénom * @ @ chaîne parent $ dernier nom dans l'en-tête, nom de famille * @ chaîne parent $ oauth_token dans l'en-tête, le jeton renvoyé par Facebook pendant OAuth pour cet utilisateur * @param chaîne $ source dans l'en-tête, la source d'où provient $ oauth_token, par exemple "facebook" par exemple [$ oauth_token] * @return obj $ identityObj avec user_id et user_token * @throws Exception non encore implémentée * / public function actionRegister ($ signature, $ app_id = ", $ email =", $ firstname = ", $ lastname =", $ oauth_token = ", $ source =")
Vous devez suivre la mise en page prescrite telle que décrite pour alimenter apidoc avec succès.
Utilisation d'arguments fictifs pour la documentation de l'API
L'équipe Yii a développé apidoc pour générer de la documentation sur le code. Cependant, comme je l'ai écrit dans Sécuriser votre API, tous les arguments, à l'exception de l'argument de signature de hachage, ont été déplacés vers les en-têtes http. Celles-ci sont invisibles pour Apidoc. Ainsi, pour générer la documentation de l'API, j'ai décidé d'utiliser une solution de contournement..
Comme vous pouvez le constater, j'inclus des arguments factices dans les méthodes, puis spécifie dans les commentaires que ceux-ci sont envoyés en tant qu'en-têtes ou "dans en-tête".
* @param string $ signature le hachage généré avec app_secret * @param string $ app_id dans l'en-tête, id d'application secrète partagée * @param string $ email dans l'en-tête, adresse email * @param string $ premier nom dans l'en-tête, prénom * @param chaîne $ nom de famille dans en-tête, nom de famille
Tant que les valeurs par défaut sont incluses dans les définitions de fonction, aucun dommage réel n’est causé:
Dans quelques instants, vous verrez comment cela fonctionne généralement avec la documentation d'API, même si ce n'est pas un style de code optimal.
Passons maintenant à l'utilisation d'apidoc pour générer la documentation.
Génération de la documentation
Vous pouvez revoir les commandes apidoc en l'exécutant sans arguments:
$ ./vendor/bin/apidoc Ceci est la version de Yii 2.0.10. Les commandes suivantes sont disponibles: - api Generate class API documentation. api / index (valeur par défaut) Fichiers de documentation de l'API Renders - guide Cette commande permet de restituer la documentation stockée sous forme de fichiers de démarcation tels que le guide yii / index (valeur par défaut) Fichiers de documentation de l'API Renders - aide Fournit des informations d'aide sur les commandes de la console. help / index (valeur par défaut) Affiche les commandes disponibles ou les informations détaillées. Pour afficher l'aide de chaque commande, entrez: apidoc help
Je vais utiliser l'option api, et voici les configurations que vous pouvez faire:
$ ./vendor/bin/apidoc help api DESCRIPTION Rend les fichiers de documentation de l'API USAGE apidoc api [… Options…] - sourceDirs (requis): array $ sourceDirs - targetDir (requis): string $ targetDir OPTIONS --appconfig: string chemin d'accès au fichier de configuration de l'application personnalisée. S'il n'est pas défini, la configuration par défaut de l'application est utilisée. --color: boolean, 0 ou 1 pour activer ou non la couleur ANSI dans la sortie. Si non défini, la couleur ANSI ne sera activée que pour les terminaux qui la prennent en charge. --exclude: string | array fichiers à exclure. --guide: chaîne URL à laquelle se trouvent les fichiers guide --guidePrefix: chaîne (par défaut, 'guide-') préfixe à ajouter à tous les noms de fichier guide. --help, -h: boolean, 0 ou 1 s'il faut afficher des informations d'aide sur la commande en cours. --interactive: boolean, 0 ou 1 (la valeur par défaut est 1) s'il faut exécuter la commande de manière interactive. --pageTitle: titre de la page de chaîne --template: string (valeur par défaut 'bootstrap') modèle à utiliser pour le rendu
Pour générer la documentation de mon API, dont le répertoire est également api, Je ferai ce qui suit:
$ ./vendor/bin/apidoc api api api / web / docs --pageTitle = MeetingPlanner TargetDirectory existe déjà. Écraser? (oui | non) [oui]: oui Recherche de fichiers à traiter… effectués. Chargement de données apidoc à partir du cache… terminé. Vérification des fichiers mis à jour… fait. 8 fichiers à mettre à jour. Traitement des fichiers… terminé. Mise à jour des références croisées et des backlinks… c'est fait. Rendu des fichiers: fait. générer des fichiers d'index d'extension… c'est fait. générer un index de recherche… fait. 35 erreurs ont été consignées dans api / web / docs / errors.txt 214 avertissements ont été consignés dans api / web / docs / warnings.txt
Parce que je n'ai pas fini de commenter tout l'arbre, des erreurs et des avertissements sont générés. Ils ressemblent le plus souvent à quelque chose comme ça:
Array ([0] => Array ([line] => 31 [fichier] => api / controllers / ParticipantController.php [message] => les comportements de méthode n'ont aucun parent à hériter dans api \ controllers \ ParticipantController.) [1 ] => Array ([line] => 32 [fichier] => api / controllers / PlaceController.php [message] => Les comportements de méthode n'ont pas de parent à hériter dans api \ controllers \ PlaceController.)
Parcourir la documentation
Publier la documentation dans la ligne de commande apidoc ci-dessus pour / api / web / docs signifie que vous pouvez parcourir la documentation de Meeting Planner à partir du Web.
Par exemple, voici le UserTokenController:
Voici la méthode actionRegister () montrant les commentaires de paramètres reflétés avec le dans l'en-tête information.
Voici la documentation de MeetingController:
Et voici la méthode actionMeetingplacechoices ():
Comme vous pouvez le constater, cela est extrêmement utile pour partager une API avec des programmeurs tiers en temps réel au moment de la livraison du code. Le grand avantage est qu'il élimine le besoin de maintenir manuellement la documentation de l'API séparément.
Chaque fois que vous pouvez éliminer une tâche pour une startup, c'est une victoire énorme.
Regarder vers l'avant
J'espère que vous avez vu un peu la puissance de l'extension apidoc de Yii2. Vous pouvez l'utiliser pour maintenir la documentation de tout votre code, et vous encourage également à suivre les commentaires, ce que je ferai plus maintenant.
Si vous avez des questions ou des commentaires, merci de les poster dans les commentaires. Si vous souhaitez suivre mes futurs tutoriels et séries d’Envato Tuts +, veuillez visiter la page de mon instructeur ou suivre @reifman. Vérifiez certainement ma série de démarrage et planificateur de réunion.
Liens connexes
Yii2 API Doc (GitHub)
Programmation avec Yii2: Construction d'une API RESTful (Envato Tuts +)
Construire votre démarrage avec PHP: Construire une API RESTful (Envato Tuts +)
Share
Ce que vous allez créer
Accentsconagua
