fgh151 / yii2-swagger

0.0.10 2025-05-19 05:59 UTC

Requires

• php: >=8.1.0
• doctrine/annotations: ^2.0
• yiisoft/yii2: ^2.0.45
• zircote/swagger-php: ^5.0

Suggests

• bower-asset/swagger-ui: Assets for render swagger ui

Apache-2.0

• Fedor B Gorsky

• swagger
• yii2

Published on Packagist.org on 2025-05-19 05:59 UTC

README

Yii2 swagger generator

Installation

The preferred way to install this extension is through composer.

Either run

php composer.phar require --prefer-dist fgh151/yii2-swagger "*"

or add

"fgh151/yii2-swagger": "*"

to the require section of your composer.json file.

Usage

1. Add module in config and set dirs with annotations

'modules' => [
    'swagger' => [
        'class' => fgh151\swagger\Module::class,
        'sources' => [
            dirname(__DIR__).'/controllers', //here can be aliases, like '@app/controllers'
            dirname(__DIR__).'/models',
        ],
        'schema' => '/api/schema', //optional depend on route config
    ],
],

1. Add routes

'rules' => [
    '/swagger/doc.json' => 'swagger/swagger/doc',
    '/swagger/ui' => 'swagger/swagger/ui',
],

1. Add controller. It can be not useful and has random name, but contain annotations. Example:

<?php

namespace app\controllers;

use OpenApi\Attributes\Info;
use OpenApi\Attributes\OpenApi;
use OpenApi\Attributes\Server;
use yii\web\Controller;

#[OpenApi(
    info: new Info(version: '1.0.0', title: 'Super API title'),
)]
#[Server(url: 'https://api.example.com', description: 'Super API description')]
class SwaggerController extends Controller
{
}

1. Add annotations to controllers. Example:

class SomeController extends \yii\web\Controller {
    #[Get(path: '/magic', summary: 'Magic API method.')]
    public function someAction() {
       //Magic here
    }
}

1. Add annotations to models. Example:

#[Schema(title: 'MyModel', description: 'Magic mode', properties: [
    new Property(property: 'Id', description: 'Идентификатор', type: 'integer'),
])]
class MyModel extends ActiveRecord
{
}

1. Add annotations to DTO. Example:

#[Schema(title: 'MyModel', description: 'Magic DTO')]
class MyModel extends ActiveRecord
{
    #[\OpenApi\Attributes\Property(title: 'Some attribute name')]
    public string $attributeName = '';
}

See annotations

Cache

To use cache for generated swagger json specify module parameters

'modules' => [
        'swagger' => [
            'class' => \fgh151\swagger\Module::class,
            'enableCache' => true,
            'cacheDuration' => 3600, //Optional, default 3600
            'cache' => 'cache', //Cache component, string|CacheInterface, optional, default 'cache'
        ],
    ]