README

基于 Yii2 框架的 Swagger 文档生成器

Swagger/OpenAPI 文档生成器，适用于 Yii2 框架。

安装

安装此扩展的首选方式是通过 composer。

运行以下命令之一

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

或者

"breadhead/yii2-swagger": "*"

将以下内容添加到你的 composer.json 文件中的 require 部分。

配置

你需要配置两个动作，如下所示

<?php

namespace app\controllers;

use Yii;
use yii\helpers\Url;
use yii\web\Controller;

/**
 * 
 * @SWG\Info(version="1.0", title="Simple API")
 */
class SiteController extends Controller
{
    /**
     * @inheritdoc
     */
    public function actions(): array
    {
        return [
            'docs' => [
                'class' => 'breadhead\swagger\SwaggerUIRenderer',
                'restUrl' => Url::to(['site/json-schema']),
            ],
            'json-schema' => [
                'class' => 'breadhead\swagger\OpenAPIRenderer',
                // Тhe list of directories that contains the swagger annotations.
                'scanDir' => [
                    Yii::getAlias('@app/controllers'),
                    Yii::getAlias('@app/models'),
                ],
            ],
            'error' => [
                'class' => 'yii\web\ErrorAction',
            ],
        ];
    }
}

使用方法

1. 创建控制器

首先，创建一个控制器类 app\controllers\UserController，如下所示

namespace app\controllers;

use app\models\User;
use yii\data\ActiveDataProvider;
use yii\rest\Controller;

/**
 * Class UserController
 */
class UserController extends Controller
{
    /**
     * @OA\Get(path="/user",
     *     tags={"User"},
     *     summary="Retrieves the collection of User resources.",
     *     @OA\Response(
     *         response = 200,
     *         description = "User collection response",
     *         @OA\Schema(ref = "#/components/schemas/User")
     *     ),
     * )
     */
    public function actionIndex()
    {
        $dataProvider = new ActiveDataProvider([
            'query' => User::find(),
        ]);

        return $dataProvider;
    }
}

1. 创建 User 定义

你需要创建文件夹 app/models/definitions，并添加 User 定义类，如下所示

<?php

namespace app\models\definitions;

/**
 * @OA\SCHEMA(required={"username", "email"})
 *
 * @OA\Property(property="id", type="integer")
 * @OA\Property(property="email", type="string")
 * @OA\Property(property="username", type="string")
 */
class User
{
}

1. 配置 URL 规则

然后，修改你的应用程序配置中的 urlManager 组件配置

'urlManager' => [
    'enablePrettyUrl' => true,
    'enableStrictParsing' => true,
    'showScriptName' => false,
    'rules' => [
        'GET,HEAD users' => 'user/index',
    ],
]

1. 启用 JSON 输入

为了使 API 能够接受 JSON 格式的输入数据，配置请求应用程序组件的 parsers 属性以使用 yii\web\JsonParser 进行 JSON 输入

'request' => [
    'parsers' => [
        'application/json' => 'yii\web\JsonParser',
    ]
]

尝试使用

现在你可以通过以下 URL 访问 Swagger 文档部分

https:///path/to/index.php?r=site/docs

在浏览器中查看