Крок 1. Встановлюємо необхідні бібліотеки
Встановлюємо бібліотеку zircote/swagger-php за допомогою composer
composer require --dev zircote/swagger-php
Завантажуємо https://github.com/swagger-api/swagger-ui та розпаковуємо вміст папки dist до папки де буде знаходитися документація, наприклад web/api-doc.
Додаємо анотації до екшенів. Приклад є в документації та прикладах (папки docs та examples) https://github.com/zircote/swagger-php . Це можна зробити і пізніше, але тоді документація буде порожня.
Приклад анотації:
/** * @OA\Info(title="My First API", version="0.1") */
Крок 2. Створюємо дію генерації документації на основі анотацій для Swagger
Створюємо контролер Swagger, для генерації документації (controllers/SwaggerController):
<?php
namespace app\controllers;
use yii\console\Controller;
use Yii;
use function OpenApi\scan;
class SwaggerController extends Controller
{
public function actionGo()
{
$openApi = scan(Yii::getAlias('@app/modules/api/controllers'));
$file = Yii::getAlias('@app/web/api-doc/swagger.yaml');
$handle = fopen($file, 'wb');
fwrite($handle, $openApi->toYaml());
fclose($handle);
return ;
}
}
Де
scan(Yii::getAlias('@app/modules/api/controllers'))
- папка з кодом та анотаціями для документування, тут ми вказали тільки один модуль для документування.
$file = Yii::getAlias('@app/web/api-doc/swagger.yaml');
- папка, в яку було скопійовано swagger-ui/dist (у прикладі це: web/api-doc).
Або створюємо консольну дію: (commands/SwaggerController):
<?php
namespace app\commands;
use yii\console\Controller;
use Yii;
use yii\console\ExitCode;
use yii\helpers\Console;
use function OpenApi\scan;
class SwaggerController extends Controller
{
public function actionGo()
{
$openApi = scan('@app/modules/api/controllers');
$file = Yii::getAlias('@web/api-doc/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 swagger/go
Крок 3. Зміна налаштувань для Swagger
Далі відкриваємо файл index.html у папці з документацією (у прикладі @app/web/api-doc/) І змінюємо параметр url з "https://petstore.swagger.io/v2/swagger.json" ( url: "https://petstore.swagger.io/v2/swagger.json", ), на "swagger.yaml" ( url: "swagger.yaml", ).
Після запуску генерації документації, вона буде доступна за адресою http://site/api-doc (Адреса може залежати від ваших налаштувань .htacces, nginx, ...)
Якщо ви використовуєте .htaccess із прикладів кодер.укр, то додайте рядок до кореневого .htaccess:
RewriteRule ^api-doc/(.*)$ web/api-doc/$1 [L]