Для документирования кода api в php можно использовать различные инструменты, например:
- phpDocumentor
- apidoc
- swagger
Во всех указанных инструментах, для генерации кода используются docBlock-и (многострочные комментарии в определенном виде).
Рассмотрим процесс подключения swagger к проекту на yii2.
Сначала установим расширение swagger-php (https://github.com/zircote/swagger-php).
Скачиваем https://github.com/swagger-api/swagger-ui и распаковываем содержимое папки dist в папку web/documentation
в yii2 (@app/web/documentation
).
Теперь создаем консольный контроллер DefaultController
:
<?php
namespace app\commands;
use OpenApi\Annotations\OpenApi;
use yii\console\Controller;
use Yii;
use yii\console\ExitCode;
use yii\helpers\Console;
use function OpenApi\scan;
class DefaultController extends Controller
{
public function actionSwagger()
{
$openApi = scan('@app/controllers');
$file = Yii::getAlias('@web/documentation/swagger.yaml');
$handle = fopen($file, 'wb');
fwrite($handle, $openApi->toYaml());
fclose($handle);
echo $this->ansiFormat('Created \n", Console::FG_BLUE);
return ExitCode::OK;
}
}
Запуск консольной команды производится командой:
php yii default/swagger
Запуск консольной команды также можно поставить на автозапуск после выполнения команды composer install
.
И последним шагом является редактирование функции window.onload
в файле @app/web/documentation/index.html
: заменяем строку url: "https://petstore.swagger.io/v2/swagger.json"",
на url: "swagger.yaml",
.
Теперь документация доступна по адресу http://ваш-сайт/documentation/index.html
{{ 'Comments (%count%)' | trans {count:count} }}
{{ 'Comments are closed.' | trans }}