Документирование API в yii2: swagger и консольный контроллер

Для документирования кода 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