README

Yii Swagger

为Yii框架提供的OpenAPI Swagger。

要求

• PHP 8.0或更高版本。

安装

可以使用Composer安装此包

composer require yiisoft/yii-swagger

配置

1. 将路由配置添加到config/routes.php

use Yiisoft\DataResponse\Middleware\FormatDataResponseAsHtml;
use Yiisoft\DataResponse\Middleware\FormatDataResponseAsJson;
use Yiisoft\Router\Group;
use Yiisoft\Router\Route;
use Yiisoft\Swagger\Middleware\SwaggerUi;
use Yiisoft\Swagger\Action\SwaggerJson;

// Swagger routes
Group::create('/swagger', [
    Route::get('')
        ->middleware(FormatDataResponseAsHtml::class)
        ->action(fn (SwaggerUi $swaggerUi) => $swaggerUi->withJsonUrl('/swagger/json-url')),
    Route::get('/json-url')
        ->middleware(FormatDataResponseAsJson::class)
        ->action(SwaggerJson::class),
]),

2. 在默认API控制器中添加注解

use OpenApi\Annotations as OA;

/**
 * @OA\Info(title="My first API", version="1.0")
 */
class DefaultController {
    // ...
}

以及在动作之前

/**
 * @OA\Get(
 *     path="/api/endpoint",
 *     @OA\Response(response="200", description="Get default action")
 * )
 */
public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
    // ...
}

有关如何对代码进行注解的详细信息，请参阅Swagger-PHP文档

3. 配置SwaggerJson动作

为了注册注解，您需要配置SwaggerJson。

您可以使用config/params.php中的参数来配置SwaggerJson

//...
'yiisoft/yii-swagger' => [
    'annotation-paths' => [
        '@src/Controller' // Directory where annotations are used
    ],
    'cacheTTL' => 60 // Enables caching and sets TTL, "null" value means infinite cache TTL.
],
//...

4. (可选) 添加别名和资源管理器的配置

use Yiisoft\Definitions\Reference;
use Yiisoft\Assets\AssetManager;

return [
    //...
    'yiisoft/aliases' => [
        'aliases' => [
            //...
            '@views' => '@root/views',
            '@assets' => '@public/assets',
            '@assetsUrl' => '@baseUrl/assets',
        ],
    ],
    'yiisoft/view' => [
        'basePath' => '@views',
        'defaultParameters' => [
            'assetManager' => Reference::to(AssetManager::class),
        ]
    ],
    //...
];

5. (可选) 配置SwaggerUi动作

您可以使用config/params.php中的参数来配置SwaggerUi。

例如，您可以将persistAuthorization参数设置为true以启用授权持久化。

//...
'yiisoft/yii-swagger' => [
    'ui-params' => [
        'persistAuthorization' => true,
    ],
],
//...

您可以通过点击链接找到参数的完整列表。

6. (可选) 配置SwaggerService

您可以在config/params.php中指定用于生成OpenApi\Annotations\OpenApi实例的选项，以配置SwaggerService

//...
'yiisoft/yii-swagger' => [
    // Default values are specified.
    'open-api-options' => [
        'aliases' => OpenApi\Generator::DEFAULT_ALIASES,
        'namespaces' => OpenApi\Generator::DEFAULT_NAMESPACES,
        'analyser' => null,
        'analysis' => null,
        'processors' => null,
        'logger' => null,
        'validate' => true,
        'version' => OpenApi\Annotations\OpenApi::DEFAULT_VERSION,
    ],
],
//...

有关生成OpenApi\Annotations\OpenApi实例的更多信息，请参阅zircote/swagger-php包的文档。

文档

• 内部

如果您需要帮助或有疑问，Yii论坛是一个不错的选择。您还可以查看其他Yii社区资源。

许可证

Yii Swagger是自由软件。它根据BSD许可证发布。有关更多信息，请参阅LICENSE

由Yii软件维护。

支持项目

关注更新