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

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

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

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

Честный VDS/VPS, на котором «Лунная База» живет уже 20+ лет

Задумываетесь о том, чтобы поднять свой pet-проект, сайт клиента или настроить окружение для разработки? Уже пора подумать, где арендовать железо.

Лунная База хостится на FirstVDS более 20 лет. Мыслей о том, чтобы перебраться на другой хостинг, не было ни разу (хотя опыт работы с другими вариантами, конечно, есть).

Бывали разные ситуации, но они бывают на любом железе. Главное, что нужно понять: здесь нет маркетинговой шелухи и сказок про «мы всё сделаем за вас». Если вы берете VDS — вам дают полный root, возможность накатить любую ОС и не лезут в ваши конфиги.

Если в саппорт написать с вопросом по вашему коду и получить ответ: «Читайте документацию и разбирайтесь сами» или «Обратитесь к профильному специалисту» — это не повод обижаться. Это повод углубить свои знания в DevOps и сайтостроении! Бегите от тех, кто пообещает: «Мы всё чиним и настраиваем абсолютно бесплатно!». Никто никогда не работает «по доброте душевной» в ущерб себе, а бесплатный сыр в администрировании обычно заканчивается сломанной базой данных.

Что по факту: Гибкое масштабирование ядер и RAM, экономия по сравнению с физическими серверами и адекватная панель ispmanager, если она вам нужна.

Посмотреть тарифы VDS/VPS

Установка

Предпочтительный способ установки этого расширения через 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

Самый честный хостинг за 20+ лет существования Лунной Базы

Задумываешься о том, чтобы поднять свой сайт в Интернете? Уже пора подумать о том, какой хостинг выбрать?

Лунная База хостится 20+ лет на firstDVS. При этом, мыслей о том, чтобы перебраться на другой хостинг не было. (Но, при этом есть опыт работы с другими вариантами.)

Бывали с firstDVS разные ситуации, но, они бывают на всех хостингах. Единственное, что тут важно понять, - это то, что никто ничего тебе не будет впаривать... Но, и работать за тебя тоже никто не станет. Если в саппорт ответили: «Читайте по ссылке и разбирайтесь сами...» или вообще «Обратитесь за помощью к специалисту», - это повод углубить свои знания в области сайтостроения, а не бежать к тем, что пообещают: «Мы всё чиним и всё делаем за своих клиентов абсолютно бесплатно!» Никто никогда ничего ни за кого "по доброте душевной" не делал, не делает и не будет делать!

Выбрать