Russian (Pусский) translation by Ilya Nikov (you can also view the original English article)
В этой серии Программировании с Yii2 я учу своих читателей использовать Yii2 Framework в PHP. Вас также может заинтересовать мое Введение в Yii Framework, в котором рассмотрены преимущества Yii и представлен обзор новинок в Yii 2.x.
Добро пожаловать! Недавно я написал о создании API REST для вашего приложения Yii и расширил пользовательские API для нашего приложения стартапа, Meeting Planner.
В сегодняшнем учебнике я расскажу вам о расширении apidoc Yii, которое автоматически создает просматриваемую документацию для вашего кода. Я собираюсь использовать его для создания документации API для Планировщика собраний.
Начинаем
Установка apidoc довольно проста. Как показано выше, вы просто добавляете пакет, используя композер.
Помимо генерации документации из кода, оно также способно генерировать документацию из разметки маркдаун и преобразовывать ее в PDF-файлы.
Например, есть документация Yii Framework, типичная документация по коду:
И вот, вот руководство Yii2, которое, как я полагаю, создано из маркдаун здесь и интегрировано с документацией кода для удобного просмотра:
Вот синтаксис документации, поддерживаемый apidoc; Он основан на phpdoc.
Как ни странно, документация для apidoc еще не завершена, но ее довольно легко использовать для базовой автодокументации.
Создание документации API
Если вы следовали моей серии статей по созданию стартапа, вам известно, что я создаю обширный API для поддержки мобильных приложений и т.д. Apidoc - идеальный способ для меня поддерживать динамическую автоматическую документацию для него.
Конечно, есть множество других веб-сервисов, которые помогут вам документировать ваш API, но я обнаружил, что apidoc Yii хорошо подходит для моих нужд, и я оценил тему стиля phpdoc, которую они используют.
Использование стандартного стиля комментариев способствует тому, что другие службы смогут легко создавать документацию из кода Planner Meeting, если я когда-либо захочу их использовать.
Создание блоков комментариев
В основном, вы создаете комментарии в своем коде, которые apidoc использует затем для создания вашей документации. Все это описано в руководстве по кодированию Yii.
Вы размещаете блок комментариев в верхней части каждого файла, как этот:
<?php /** * @link https://meetingplanner.io * @copyright Copyright (c) 2016 Lookahead Consulting * @license https://github.com/newscloud/mp/blob/master/LICENSE */
И вы помещаете блок комментариев над каждым контроллером или определением модели:
/**
* UserTokenController provides API functionality for registration, delete and verify
*
* @author Jeff Reifman <jeff@meetingplanner.io>
* @since 0.1
*/
class UserTokenController extends Controller
{
Затем вы помещаете подробный блок комментариев над каждым методом, который включает параметры, возвращаемые значения и исключения:
/**
* Register a new user with an external social Oauth_token
*
* @param string $signature the hash generated with app_secret
* @param string $app_id in header, the shared secret application id
* @param string $email in header, email address
* @param string $firstname in header, first name
* @param string $lastname in header, last name
* @param string $oauth_token in header, the token returned from Facebook during OAuth for this user
* @param string $source in header, the source that the $oauth_token is from e.g. 'facebook' e.g. [$oauth_token]
* @return obj $identityObj with user_id and user_token
* @throws Exception not yet implemented
*/
public function actionRegister($signature,$app_id='',$email='',$firstname ='',$lastname='',$oauth_token='',$source='') {
Вы должны следовать предписанному шаблону, как описано для успешного использования apidoc.
Использование плейсхолдеров для документации API
Команда Yii разработала apidoc для генерации документации по коду. Однако, как я писал в разделе «Обеспечение безопасности вашего API», все аргументы, кроме аргумента подписи хэша, были перенесены в заголовки http. Они невидимы для apidoc. Таким образом, для создания документации API я решил использовать обходной путь.
Как вы можете видеть, я включаю фиктивные аргументы в методы, а затем указываю в комментариях, что они отправляются в виде заголовков или «в заголовке».
* @param string $signature the hash generated with app_secret * @param string $app_id in header, the shared secret application id * @param string $email in header, email address * @param string $firstname in header, first name * @param string $lastname in header, last name
Пока значения по умолчанию включены в определения функций, никакого реального вреда не будет:
public function actionRegister($signature,$app_id='',$email='',$firstname ='',
$lastname='',$oauth_token='',$source='') {
Вы увидите, как это работает для документации API, даже если это не является оптимальным стилем кодирования.
Давайте перейдем к использованию apidoc для создания документации.
Создание документации
Вы можете просмотреть команды apidoc, запустив его без аргументов:
$ ./vendor/bin/apidoc
This is Yii version 2.0.10.
The following commands are available:
- api Generate class API documentation.
api/index (default) Renders API documentation files
- guide This command can render documentation stored as
markdown files such as the yii guide
guide/index (default) Renders API documentation files
- help Provides help information about console commands.
help/index (default) Displays available commands or the detailed
information
To see the help of each command, enter:
apidoc help <command-name>
Я буду использовать опцию api, и вот пример конфигурации, которую вы можете сделать:
$ ./vendor/bin/apidoc help api DESCRIPTION Renders API documentation files USAGE apidoc api <sourceDirs> <targetDir> [...options...] - sourceDirs (required): array $sourceDirs - targetDir (required): string $targetDir OPTIONS --appconfig: string custom application configuration file path. If not set, default application configuration is used. --color: boolean, 0 or 1 whether to enable ANSI color in the output. If not set, ANSI color will only be enabled for terminals that support it. --exclude: string|array files to exclude. --guide: string url to where the guide files are located --guidePrefix: string (defaults to 'guide-') prefix to prepend to all guide file names. --help, -h: boolean, 0 or 1 whether to display help information about current command. --interactive: boolean, 0 or 1 (defaults to 1) whether to run the command interactively. --pageTitle: string page title --template: string (defaults to 'bootstrap') template to use for rendering
Чтобы сгенерировать мою документацию по API в каталог api, я сделаю следующее:
$ ./vendor/bin/apidoc api api api/web/docs
--pageTitle=MeetingPlanner
TargetDirectory already exists. Overwrite? (yes|no) [yes]:yes
Searching files to process... done.
Loading apidoc data from cache... done.
Checking for updated files... done.
8 files to update.
Processing files... done.
Updating cross references and backlinks... done.
Rendering files: done.
generating extension index files...done.
generating search index...done.
35 errors have been logged to api/web/docs/errors.txt
214 warnings have been logged to api/web/docs/warnings.txt
Поскольку я не закончил комментирование всего дерева, возникают ошибки и предупреждения. Они чаще всего выглядят примерно так:
Array
(
[0] => Array
(
[line] => 31
[file] => api/controllers/ParticipantController.php
[message] => Method behaviors has no parent to inherit from in api\controllers\ParticipantController.
)
[1] => Array
(
[line] => 32
[file] => api/controllers/PlaceController.php
[message] => Method behaviors has no parent to inherit from in api\controllers\PlaceController.
)
Просмотр документации
Публикация документации в приведенной выше командной apidoc строка /api/web/docs означает, что вы можете просматривать документацию Планировщика собраний из Интернета.
Например, вот UserTokenController:
Вот метод actionRegister(), показывающий комментарии параметров, отраженные в информации in header.
Вот документация MeetingController:
И вот метод actionMeetingplacechoices():
Как видите, это может быть чрезвычайно полезно для совместного использования API с сторонними программистами в режиме реального времени при доставке кода. Огромное преимущество заключается в том, что это устраняет необходимость вручную поддерживать документацию API отдельно от основного кода.
В любое время вы можете устранить задачу для запуска генерации кода.
Что дальше
Я надеюсь, что вы увидели немного возможностей расширения AIDOC Yii2. Вы можете использовать его для поддержки документации для всего вашего кода.
Если у вас есть какие-либо вопросы или отзывы, разместите их в комментариях. Если вы не хотите пропустить мои будущие учебные пособия Envato Tuts +, посетите мою страницу инструктора или следуйте за мной в Твиттер @reifman. Определенно проверьте мою серию про стартап и Планировщик встреч.
Ссылки по теме
