В этой серии «Программирование с Yii2» я расскажу читателям, как использовать Yii2 Framework для PHP. Возможно, вас также заинтересует мое Введение в Yii Framework , в котором рассматриваются преимущества Yii и содержится обзор того, что нового в Yii 2.x.
Добро пожаловать! Недавно я написал о создании REST API для вашего приложения Yii и о расширенных пользовательских API для нашего приложения серии Startup , Meeting Planner.
В сегодняшнем уроке я познакомлю вас с расширением apidoc в Yii , которое автоматически генерирует доступную для просмотра документацию для вашего кода. Я собираюсь использовать его для создания документации API для Meeting Planner.
Начиная
Установить apidoc легко. Как показано выше, вы просто добавляете пакет, используя composer.
Помимо создания документации из кода, она также способна создавать документацию из уценки и преобразовывать ее в PDF-файлы.
Например, есть документация по Yii Framework , типичная документация по коду:
И вот руководство Yii2 , которое, я считаю, создано на основе уценки и интегрировано с документацией кода для удобного просмотра:
Вот синтаксис документации, который поддерживает apidoc ; это основано на phpdoc .
Как ни странно, документация для apidoc еще не завершена, но ее довольно просто использовать для базовой автоматической документации.
Создание документации API
Если вы следили за моей серией стартапов , вы знаете, что я создаю обширный API для поддержки мобильных приложений и т. Д. Apidoc — это идеальный способ для меня поддерживать динамическую автоматизированную документацию для него.
Конечно, есть много других веб-сервисов, которые помогут вам документировать ваш API, но я обнаружил, что apidoc в Yii хорошо подошел для моих нужд, и я высоко оценил тему в стиле phpdoc, которую они используют.
Использование стандартного стиля комментирования повышает вероятность того, что другие службы смогут легко создавать документацию из кода Meeting Planner, если я когда-нибудь захочу их использовать.
Создание блоков комментариев
По сути, вы создаете комментарии в своем коде, которые apidoc использует для создания вашей документации. Это описано в руководстве по стилю кодирования Yii .
Вы размещаете блок комментариев в верхней части каждого файла, как этот:
|
1
2
3
4
5
6
|
<?php
/**
* @link https://meetingplanner.io
* @copyright Copyright (c) 2016 Lookahead Consulting
* @license https://github.com/newscloud/mp/blob/master/LICENSE
*/
|
И вы помещаете блок комментария над каждым определением контроллера или модели:
|
1
2
3
4
5
6
7
8
|
/**
* UserTokenController provides API functionality for registration, delete and verify
*
* @author Jeff Reifman <[email protected]>
* @since 0.1
*/
class UserTokenController extends Controller
{
|
Затем вы помещаете подробный блок комментариев над каждым методом, который включает параметры, возвращаемые значения и исключения:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
|
/**
* 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 eg ‘facebook’ eg [$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 я решил использовать обходной путь.
Как видите, я включаю в методы фиктивные аргументы, а затем в комментариях указываю, что они отправляются в виде заголовков или «в заголовке».
|
1
2
3
4
5
|
* @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
|
Пока значения по умолчанию включены в определения функций, реального вреда не будет:
|
1
2
|
public function actionRegister($signature,$app_id=»,$email=»,$firstname =»,
$lastname=»,$oauth_token=»,$source=») {
|
Вскоре вы увидите, как это обычно работает с документацией API, даже если это не оптимальный стиль кодирования.
Давайте перейдем к фактическому использованию apidoc для генерации документации.
Генерация документации
Вы можете просмотреть команды apidoc, запустив его без аргументов:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
|
$ ./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, и вот конфигурации, которые вы можете сделать:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
|
$ ./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 , я сделаю следующее:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
|
$ ./vendor/bin/apidoc api api api/web/docs
—pageTitle=MeetingPlanner
TargetDirectory already exists.
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
|
Поскольку я не закончил комментировать все дерево, появляются ошибки и предупреждения. Чаще всего они выглядят примерно так:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
|
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 означает, что вы можете просматривать документацию Meeting Planner из Интернета.
Например, вот UserTokenController :
Вот метод actionRegister (), показывающий комментарии параметров, отраженные с информацией in header .
Вот документация MeetingController :
И вот метод actionMeetingplacechoices () :
Как видите, это очень полезно для обмена API со сторонними программистами в режиме реального времени при доставке кода. Большим преимуществом является то, что это устраняет необходимость отдельного ведения документации API отдельно.
В любое время вы можете устранить задачу для стартапа, это огромная победа.
Заглядывая вперед
Я надеюсь, что вы видели немного силы расширения apidoc в Yii2. Вы можете использовать его, чтобы поддерживать документацию для всего вашего кода, а также он побуждает вас не отставать от комментариев, что я сделаю больше сейчас.
Если у вас есть какие-либо вопросы или отзывы, пожалуйста, оставьте их в комментариях. Если вы хотите быть в курсе моих будущих уроков Envato Tuts + и других серий, пожалуйста, посетите мою страницу инструктора или следуйте @reifman . Обязательно посмотрите мою серию стартапов и Планировщик собраний .