Генератор документации API

Генератор документации API для Yii 2

Это расширение предоставляет генератор документации API для Yii framework 2.0.

Для получения информации о лицензии проверьте LICENSE-file.

Установка

Предпочтительный способ установки этого расширения через composer.

Либо запустить

composer require --prefer-dist yiisoft/yii2-apidoc

Приведенная выше команда может не работать в существующем проекте из-за конфликтов версий, которые необходимо разрешить, поэтому рекомендуется добавить пакет вручную в раздел require вашего composer.json:

"yiisoft/yii2-apidoc": "~2.1.0"

после этого запустите команду composer update. Вы также можете запустить composer update yiisoft/yii2-apidoc cebe/markdown если вы хотите избежать обновления несвязанных пакетов.

Использование

Это расширение использует две команды:

• api для создания документации API класса.
• guide для визуализации хороших HTML-страниц из файлов markdown, таких как руководство yii.

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

vendor/bin/apidoc api source/directory ./output

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

vendor/bin/apidoc guide source/docs ./output

Вы можете объединить их для создания API класса и документации в одном месте:

## порядок важен для того, чтобы позволить руководству связать себя с apidoc
# создание документов API
vendor/bin/apidoc api source/directory ./output
# сгенерируйте руководство
vendor/bin/apidoc guide source/docs ./output

По умолчанию будет использован шаблон bootstrap. Вы можете выбрать другой шаблон с помощью --template=name параметра. В настоящее время доступен только шаблон bootstrap.

Вы также можете добавить: yii\apidoc\commands\ApiController и GuideController для карты команд консольного приложения и запускать их как консольное приложение.

Создание документов из нескольких источников

Генератор apidoc может использовать несколько каталогов, поэтому вы можете создавать документы для вашего приложения и включать Yii framework документы для включения связей между вашими классами и классами фреймворка. Это также позволяет @inheritdoc работать с классами, которые расширяются из фреймворка. Используйте следующую команду для создания объединенных документов api:

./vendor/bin/apidoc api ./vendor/yiisoft/yii2,. docs/json --exclude="docs,vendor"

Это позволит прочитать исходные файлы из ./vendor/yiisoft/yii2 папки и . который является текущим каталогом (вы можете заменить его на расположение вашего кода, если он не находится в текущем рабочем каталоге).

Расширенное использование

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

#!/bin/sh

# установите пути в соответствии с вашим окружением
YII_PATH=~/dev/yiisoft/yii2
APIDOC_PATH=~/dev/yiisoft/yii2/extensions/apidoc
OUTPUT=yii2docs

cd $APIDOC_PATH
./apidoc api $YII_PATH/framework/,$YII_PATH/extensions $OUTPUT/api --guide=../guide-en --guidePrefix= --interactive=0
./apidoc guide $YII_PATH/docs/guide    $OUTPUT/guide-en --apiDocs=../api --guidePrefix= --interactive=0
./apidoc guide $YII_PATH/docs/guide-ru $OUTPUT/guide-ru --apiDocs=../api --guidePrefix= --interactive=0
# повторить последнюю фразу на нескольких языках

Создание PDF-файла руководства

Используйте pdflatex и GNU make для этого.

vendor/bin/apidoc guide source/docs ./output --template=pdf
cd ./output
make pdf

Если всё отработает без ошибок, ищите файл guide.pdf в output папке.

Специальный синтаксис Markdown

Имеется специальный синтаксис для связывания с классами в документации API. Подробности смотри в руководстве по стилю кода.

Создание собственных шаблонов

TBD

Использование слоя модели

TBD

Заберите ссылку на статью к себе, чтобы потом легко её найти!
Раз уж досюда дочитали, то может может есть желание рассказать об этом месте своим друзьям, знакомым и просто мимо проходящим?
Не надо себя сдерживать! ;)