php yii2-swagger 语法及使用及常用注释说明

2810NG

已于 2022-12-25 19:23:34 修改

阅读量815

点赞数 1

文章标签： php 开发语言

于 2022-12-25 19:21:17 首次发布

本文链接：https://blog.csdn.net/qq_35456384/article/details/127910576

版权

前言

swagger-php 和 yii2-swagger 是一样的东西，注释语法都是一样的，核心也是注释语法说明，工作中需要给前端做文档。

程序员讨厌的两件事大家都懂：讨厌别人别写文档，讨厌写文档。

综合考虑下来，选择swagger比较合适，swagger也符合接口开放规范openapi。

一、yii2-swagger 安装

已经安装了composer了吧？执行命令：

php composer.phar require --prefer-dist light/yii2-swagger "~3.0" --dev

或者在composer.json 中加入：

"light/yii2-swagger": "~3.0"

运行 composer update

旧项目就不要用方法2了，一堆问题！！！

等待安装完成～

二、引入swagger

在项目中找你需要引入swagger的模块下，创建个控制器，例如SwaggerController.php，复制一下代码

代码如下（示例）：

public function actions()
{
    return [
        //The document preview addesss:http://api.yourhost.com/site/doc
        'doc' => [
            'class' => 'light\swagger\SwaggerAction',
            'restUrl' => \yii\helpers\Url::to(['/site/api'], true),
        ],
        //The resultUrl action.
        'api' => [
            'class' => 'light\swagger\SwaggerApiAction',
            //The scan directories, you should use real path there.
            'scanDir' => [
                Yii::getAlias('@api/modules/v1/swagger'),
                Yii::getAlias('@api/modules/v1/controllers'),
                Yii::getAlias('@api/modules/v1/models'),
                Yii::getAlias('@api/models'),
            ],
            //The security key
            'api_key' => 'balbalbal',
        ],
    ];
}

doc是文档地址，api是swagger生成的json地址

restUrl 是指向swagger生成的json地址，例如：swagger/doc 是文档，swagger/api是生成json的地址，

scanDir 是扫描地址，也就是api扫描的目录

api_key 是配置访问文档的密钥（新版本一点叼用都没有，不知道是不是我的问题）

更多方法可以点击对应class查看配置。这里不多介绍了。

2.注释说明

使用swagger-php之前必须需要一个主要描述头, 并且必须在类的上方，api接口必须在方法上方，如原有限制必须放在swagger之上

代码如下（示例）：

/**
 * @OA\Info(
 *  title="xx管理平台API - v1.0.0",
 *  version="1.0",
 *  description="甲方管理API",
 * ),

 * @OA\Tag(
 *     name="登录鉴权",
 *     description = "用户登录鉴权，安全秘钥获取、登录状态、登出"
 * )
 * @OA\Tag(
 *     name="产品管理",
 *     description = "产品管理"
 * )
 * @OA\server(
 *      url="http://dev.xxx.top/v1/",
 *      description="开发环境",
 * )
 * @OA\server(
 *      url="http://test.xxx.com/v1/",
 *      description="测试环境",
 * )
 * @OA\server(
 *      url="http://test.xxx.com/v1/",
 *      description="正式环境【Warning】",
 * )
 *
 */

api接口注释示例：

/**
     * 账户列表
     * @OA\POST(
     * path="/manager/index",
     * tags={"甲方账号管理"},operationId="manager-index",summary="账户列表",
     * @OA\RequestBody(
     *     description="请求成功",
     *     @OA\MediaType(  mediaType="application/x-www-form-urlencoded",
     *          @OA\Schema(
     *              @OA\Property(   property="page_size",  type="integer",  description="分页大小"),
     *              @OA\Property(property="page", type="integer",description="分页号"),
      *          )
     *     )
     * ),
     * @OA\Response(
     *     response=200,
     *     description="请求成功",
     *      @OA\JsonContent(
     *          @OA\Property(property="list", type="array",description="数据列表",
     *               @OA\Items(type="object",
     *                    @OA\Property(property="id", type="string",description="主键"),
     *                     @OA\Property(property="username", type="string",description="甲方账号"),
     *                     @OA\Property(property="realname", type="string",description="甲方姓名"),
     *                      @OA\Property(property="sms_mobile", type="integer",description="验证手机号"),
     *                      @OA\Property(property="distribute_state", type="integer",description="分配状态:0=未分配，1=分配"),
     *                )
     *           ),
     *          @OA\Property(property="pagination", type="array",description="分页数据",
     *                  @OA\Items(type="object",
     *                    @OA\Property(property="pageParam", type="string",description="页码参数名",),
     *                    @OA\Property(property="pageSizeParam", type="string",description="分页大小参数",),
     *                    @OA\Property(property="route", type="string",description="路由",),
     *                    @OA\Property(property="params", type="string",description="参数",),
     *                    @OA\Property(property="urlManager", type="string",description="路径",),
     *                    @OA\Property(property="validatePage", type="integer",description="验证分页",),
     *                    @OA\Property(property="totalCount", type="integer",description="分页总数",),
     *                    @OA\Property(property="defaultPageSize", type="integer",description="默认分页大小",),
     *                    @OA\Property(property="pageSizeLimit", type="object",description="分页数据",),
     *                ),
     *          ),
     *         @OA\Examples(example="status-1",description="成功出参", summary="成功响应 status=1",
     *                             value={ "list":{"id":"1","username":"测试","realname":"测试","sms_mobile":"18888888888","distribute_state":1}} ),
     *     )
     * ),
     * @OA\Response(
     *     response=422,
     *     description="请求失败",
     *     @OA\JsonContent(type="object",
     *          @OA\Examples(example="status-0", description="失败出参",summary="失败响应 status=0",
     *                                       value={"status":0,"info":"参数错误","data":{} } ),
     *     )
     * ),
     * )
     */