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 软件 维护。

支持项目

关注更新