Генерация swagger документации в yii2

Для начала установим зависимости:

composer require zircote/swagger-php doctrine/annotations

В конфигурации, в разделе маршрутиризации добавим обработчик

'urlManager' => [
    'enablePrettyUrl' => true,
    'showScriptName' => false,
    'rules' => [
        '/swagger/doc.json' => 'swagger/doc',
    ],
],

И создадим сам контроллер


use OpenApi\Attributes\Info;
use OpenApi\Attributes\OpenApi;
use OpenApi\Generator;
use Yii;
use yii\helpers\Json;
use yii\web\Controller;

#[OpenApi(
    info: new Info(version: '1.0.0', title: 'API'),
)]
class SwaggerController extends Controller
{
    public function actionDoc()
    {
        $openapi = Generator::scan([
            Yii::getAlias('@app/controllers'),
            Yii::getAlias('@app/models'),
        ]);

        $this->asJson(Json::decode($openapi->toJson()));
    }
}

Мы используем нативные аннотации для генерации описания. Указываем в каких папках искать модели и контроллеры. В конце отдаем все это клиенту.Теперь создадим модель

use OpenApi\Attributes\Property;
use OpenApi\Attributes\Schema;#[Schema(title: 'Storage upload model', properties: [
new Property(property: 'file', title: 'file', description: 'File to upload', type: 'file', format: 'binary'),
new Property(property: 'entity', title: 'entity', description: 'Entity name'),
new Property(property: 'entity_id', title: 'entity_id', description: 'Entity id'),
])]
class Storage extends ActiveRecord {}

И В контроллере функцию, котороая будет что то делать

#[Post(path: '/storage/upload', description: 'Upload file', parameters: [
    new Parameter(name: 'file', description: 'File', in: 'query', required: true, schema: new Schema(ref: '#/components/schemas/Storage')),
])]
#[Response(response: 200, description: 'Upload result', content: new JsonContent(
    properties: [
        new Property(property: 'id', title: 'id', description: 'ID', type: 'integer', example: 1),
        new Property(property: 'message', title: 'message', description: 'Message', type: 'string', example: 'OK'),
        new Property(property: 'url', title: 'url', description: 'URL', type: 'string', example: 'https://example.com/image.png'),
    ]
))]
#[Response(response: 400, description: 'Error', content: new JsonContent(
    properties: [
        new Property(property: 'error', title: 'error', description: 'Error', type: 'string', example: 'File not uploaded'),
    ]
))]
public function actionUpload(){}

Теперь по адресу /swagger/doc.json будет лежать актуальная документация

Теги:

Контакты

Аккаунты