Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. Automation
Code

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

by
Difficulty:IntermediateLength:ShortLanguages:
This post is part of a series called Building Your Startup With PHP.
How to Build a User Tour With Shepherd in JavaScript
This post is part of a series called How to Program With Yii2.
Programming With Yii2: Building Community With Voting, Comments, and Sharing

Russian (Pусский) translation by Ilya Nikov (you can also view the original English article)

Final product image
What You'll Be Creating

В этой серии Программировании с Yii2 я учу своих читателей использовать Yii2 Framework в PHP. Вас также может заинтересовать мое Введение в Yii Framework, в котором рассмотрены преимущества Yii и представлен обзор новинок в Yii 2.x.

Добро пожаловать! Недавно я написал о создании API REST для вашего приложения Yii и расширил пользовательские API для нашего приложения стартапа, Meeting Planner.

В сегодняшнем учебнике я расскажу вам о расширении apidoc Yii, которое автоматически создает просматриваемую документацию для вашего кода. Я собираюсь использовать его для создания документации API для Планировщика собраний.

Начинаем

Programming With Yii - APIdoc installation Guide

Установка apidoc довольно проста. Как показано выше, вы просто добавляете пакет, используя композер.

Помимо генерации документации из кода, оно также способно генерировать документацию из разметки маркдаун и преобразовывать ее в PDF-файлы.

Например, есть документация Yii Framework, типичная документация по коду:

Programming With Yii - Auto-Generated Framework Documentation

И вот, вот руководство Yii2, которое, как я полагаю, создано из маркдаун здесь и интегрировано с документацией кода для удобного просмотра:

Programming With Yii Generating Documentation - Guide generated from Markdown

Вот синтаксис документации, поддерживаемый apidoc; Он основан на phpdoc.

Как ни странно, документация для apidoc еще не завершена, но ее довольно легко использовать для базовой автодокументации.

Создание документации API

Если вы следовали моей серии статей по созданию стартапа, вам известно, что я создаю обширный API для поддержки мобильных приложений и т.д. Apidoc - идеальный способ для меня поддерживать динамическую автоматическую документацию для него.

Конечно, есть множество других веб-сервисов, которые помогут вам документировать ваш API, но я обнаружил, что apidoc Yii хорошо подходит для моих нужд, и я оценил тему стиля phpdoc, которую они используют.

Использование стандартного стиля комментариев способствует тому, что другие службы смогут легко создавать документацию из кода Planner Meeting, если я когда-либо захочу их использовать.

Создание блоков комментариев

В основном, вы создаете комментарии в своем коде, которые apidoc использует затем для создания вашей документации. Все это описано в руководстве по кодированию Yii.

Вы размещаете блок комментариев в верхней части каждого файла, как этот:

И вы помещаете блок комментариев над каждым контроллером или определением модели:

Затем вы помещаете подробный блок комментариев над каждым методом, который включает параметры, возвращаемые значения и исключения:

Вы должны следовать предписанному шаблону, как описано для успешного использования apidoc.

Использование плейсхолдеров для документации API

Команда Yii разработала apidoc для генерации документации по коду. Однако, как я писал в разделе «Обеспечение безопасности вашего API», все аргументы, кроме аргумента подписи хэша, были перенесены в заголовки http. Они невидимы для apidoc. Таким образом, для создания документации API я решил использовать обходной путь.

Как вы можете видеть, я включаю фиктивные аргументы в методы, а затем указываю в комментариях, что они отправляются в виде заголовков или «в заголовке».

Пока значения по умолчанию включены в определения функций, никакого реального вреда не будет:

Вы увидите, как это работает для документации API, даже если это не является оптимальным стилем кодирования.

Давайте перейдем к использованию apidoc для создания документации.

Создание документации

Вы можете просмотреть команды apidoc, запустив его без аргументов:

Я буду использовать опцию api, и вот пример конфигурации, которую вы можете сделать:

Чтобы сгенерировать мою документацию по API в каталог api, я сделаю следующее:

Поскольку я не закончил комментирование всего дерева, возникают ошибки и предупреждения. Они чаще всего выглядят примерно так:

Просмотр документации

Публикация документации в приведенной выше командной apidoc строка /api/web/docs означает, что вы можете просматривать документацию Планировщика собраний из Интернета.

Например, вот UserTokenController:

Programming With Yii Generating Documentation - UserTokenController Example

Вот метод actionRegister(), показывающий комментарии параметров, отраженные в информации in header.

Programming With Yii Generating Documentation - UserTokenController Example actionRegister method

Вот документация MeetingController:

Programming With Yii Generating Documentation - MeetingController Example

И вот метод actionMeetingplacechoices():

Programming With Yii Generating Documentation - MeetingController Example actionMeetingplaces example

Как видите, это может быть чрезвычайно полезно для совместного использования API с сторонними программистами в режиме реального времени при доставке кода. Огромное преимущество заключается в том, что это устраняет необходимость вручную поддерживать документацию API отдельно от основного кода.

В любое время вы можете устранить задачу для запуска генерации кода.

Что дальше

Я надеюсь, что вы увидели немного возможностей расширения AIDOC Yii2. Вы можете использовать его для поддержки документации для всего вашего кода.

Если у вас есть какие-либо вопросы или отзывы, разместите их в комментариях. Если вы не хотите пропустить мои будущие учебные пособия Envato Tuts +, посетите мою страницу инструктора или следуйте за мной в Твиттер @reifman. Определенно проверьте мою серию про стартап и Планировщик встреч.

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

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.