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

前言

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":{} } ),
     *     )
     * ),
     * )
     */

2.1 @OA/Info  文档信息配置

文档有蛮多属性的，具体常用有以上的：

属性列表

---

• title:string

        文档标题，例如：title="xxx"

• version:string

        文档版本

• description:string

        文档描述

2.2 @OA/Tag  文档api分组信息

属性列表

---

• name:string

        分组名称，例如：name="xxx"

• description:string

        分组描述

2.3 @OA/server  文档请求服务地址

属性列表

---

• url:string

        服务地址，例如：url="xxx.com"

• description:string

        服务地址描述

2.4 @OA/POST/GET/PUT  接口请求方式

所有组件都要在这里面编写

属性列表

---

• path:string

        接口地址

• tags:string

        所属分组，对象。例如  tags={"甲方账号管理"}

• operationId:string
  

   方法操作唯一id，不能相同，否则报错！

• summary:string

        接口描述

2.5 @OA\RequestBody 请求body体

post/json内容都会在此写入

属性列表

• required:bool
  

   是否必须输入

• description:string

        内容体描述

2.6 @OA\MediaType 请求类型

可以是 application/json 类型，或者form表单类型：mediaType="application/x-www-form-urlencoded" 等等...

属性列表

• mediaType:string
  

   请求类型，例如：mediaType="application/x-www-form-urlencoded"

2.7 @OA\Schema 请求示例

属性列表

• title:string
  

   示例标题

• description:string 

        示例描述

• type:string 

        示例类型，属性的类型。值必须是“string”、“number”、“integer”、“boolean”、“array”或“object”。

2.8 @OA\Property 请求参数

属性列表

• property:string
  

   请求name名

• description:string 

        参数描述

• type:string 

        示例类型，属性的类型。值必须是“string”、“number”、“integer”、“boolean”、“array”或“object”。

2.9 @OA\Response 请求响应

属性列表

• response:string
  

   响应状态码：200/500/403/404....

• description:string 

        响应描述

2.10 @OA\JsonContent 响应的是json体

2.11 @OA\Items 数组项列表

2.12 @OA\Examples 参数示例描述

属性列表

• example:string
  

   属性id

• description:string 

        示例值描述

• summary:string

         示例标题

• value:string

        示例值，json形式表示，例如：value={"xxx":"xxx"}

最终生成以下效果：