Программирование с помощью Yii: Создание документации

В этой серии Программировании с 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. Определенно проверьте мою серию про стартап и Планировщик встреч.

Ссылки по теме

• Yii2 API Doc (GitHub)
• Программирование с Yii2: создание API RESTful (Envato Tuts +)
  
• Создание стартапа на PHP: создание API RESTful (Envato Tuts +)
• Yii2 Developer Exchange