Swagger框架 API文档速成

Swagger 斯瓦格 / 丝袜哥

SwaggerHP_Build.png

Swagger中式汉语：
丝袜哥? 斯瓦格? 有没有很熟悉，当然不是你想的 格瓦斯 那是饮料！
Swagger给人第一印象就是【最（hen）流（niu）行（bai）】；

我们为什么要用Swagger文档？
1.自动化文档，代替手写API的web工具，代替MarkDown、world文档、还有比较low的微信讲述哈哈
2.配合swagger-ui我们只需要把参数写在注释里面就生成了文档
3.在线动态测试API接口，相当于postman一样调用接口返回数据success/error/data
// 下面有两种使用方式，都可以使用只要实现最终展示给前端文档目的就可以

1. Swagger编辑json使用方法：

用 Composer 安装在框架中使用

使用配置到 Laravel 框架中

使用 swagger-ui + swagger-edit
下载 Swagger-ui 只需要 dist 里面的文件放在项目根目录 public 下并配置上路由使用访问。
下载 Swagger-editor 只要 dist 目录的东西和根目录的index.html 按照官方OpenAPI规范给出的语法使用编辑。

2. 代码注释解析使用方法：

phpStorm安装组件 (安装组件Swagger Plugin 和 PHP Annotations)

第一个组件CodeGlance是（侧栏代码地图）这个和swagger没有关系
只需要安装Swagger Plugin和PHP Annotations，安装如果超时提示
Plugin Swagger Plugin was not installed: Cannot download无法下载：
查看解决方法：CSDN-phpStorm安装组件超时

phpStorm组件.png

PHPStorm配置自动补全

配置IDE自动补全功能

配置IDE自动补全.png

配置IDE自动补全信息

• 控制器里注释用 (Abbreviation:swaggerController Description:swagger)

@SWG\Post(
*     path="/register",
*     tags={"User"},
*     summary="接口名称",
*     description="接口描述信息",
*     operationId="register-store",
*     produces={"application/json"},
*     @SWG\Parameter(ref="#/parameters/Authorization"),
*     @SWG\Response(
*         response=200,
*         description="注册成功",
*         @SWG\Schema(ref="#/definitions/success"),
*     ),
*     @SWG\Response(
*         response=422,
*         description="注册失败",
*     ),
* )

• Parameter.php使用 (Abbreviation:swaggerParameter Description:swagger)

*******************************paraName
 * @SWG\Parameter(
 *    parameter="输入框对应控制器寻找名",
 *    name="输入框名称",
 *    description="输入框描述",
 *    in="header",        // 放在/header/query(链接)/formData/body/path
 *    type="string",      // integer/float/string/boolean/object/password(模糊输入) byte(编码的字符base64)
 *    format="string",    // integer/float/string/boolean/object/password(模糊输入) byte(编码的字符base64)
 *    required=true,      // 输入框不能为空
 *    enum={"0",0,1},     // 可以加枚举
 * ),
 * *******************************end

• 接口详情描述-first()单数据注释用 (Abbreviation:swaggerDefinition-first Description:swagger)

@SWG\Definition(
*     definition="user-index",
*     type="object",
*     required={"status","code","message","data"},
*     @SWG\Property(
*         property="status",
*         type="boolean",
*         example="true",
*         description="请求状态",
*     ),
*     @SWG\Property(
*         property="code",
*         type="integer",
*         example=200,
*         description="状态码",
*     ),
*     @SWG\Property(
*         property="message",
*         type="string",
*         example="操作成功",
*         description="状态语义",
*     ),
*     @SWG\Property(
*         property="data",
*         type="object",
*         @SWG\Property(
*             property="id",
*             type="integer",
*             example=1,
*         ),
*         @SWG\Property(
*             property="user",
*             type="array",
*             @SWG\Items(
*                 type="object",
*                 @SWG\Property(
*                     property="user_id",
*                     type="integer",
*                     example=1,
*                 ),
*                 @SWG\Property(
*                     property="username",
*                     type="string",
*                     example="三脚猫",
*                 ),
*             ),
*         ),
*         @SWG\Property(
*             property="hello",
*             type="string",
*             example="helloWorld",
*         ),
*     ),
* ),

• 接口详情描述-get()多数据注释用 (Abbreviation:swaggerDefinition-get Description:swagger)

@SWG\Definition(
 *     definition="user-userInfo-index",
 *     type="object",
 *     required={"status","code","message","data"},
 *     allOf={
 *          @SWG\Schema(
 *              required={"data"},
 *              @SWG\Property(
 *                  property="status",
 *                  type="boolean",
 *                  example="true",
 *                  description="请求状态",
 *              ),
 *              @SWG\Property(
 *                  property="code",
 *                  type="integer",
 *                  example=200,
 *                  description="状态码",
 *              ),
 *              @SWG\Property(
 *                  property="message",
 *                  type="string",
 *                  example="操作成功",
 *                  description="状态语义",
 *              ),
 *              @SWG\Property(
 *                  property="data",
 *                  type="array",
 *                  @SWG\Items(
 *                      type="object",
 *                      required={"user_id"},
 *                      @SWG\Property(
 *                          property="user_id",
 *                          type="integer",
 *                          example=1,
 *                          description="可有可无的字段描述",
 *                      ),
 *                      @SWG\Property(
 *                          property="username",
 *                          type="string",
 *                          example="三脚猫",
 *                      ),
 *                  ),
 *             ),
 *          )
 *     },
 * ),

• 接口详情描述-paginate()分页数据注释用 (Abbreviation:swaggerDefinition-get-paginate Description:swagger)

@SWG\Definition(
*     definition="user-update",
*     type="object",
*     required={"status","code","message","data"},
*     allOf={
*         @SWG\Schema(
*             required={"data"},
*             @SWG\Property(
*                 property="status",
*                 type="boolean",
*                 example="true",
*                 description="请求状态",
*             ),
*             @SWG\Property(
*                 property="code",
*                 type="integer",
*                 example=200,
*                 description="状态码",
*             ),
*             @SWG\Property(
*                 property="message",
*                 type="string",
*                 example="操作成功",
*                 description="状态语义",
*             ),
*             @SWG\Property(
*                 property="data",
*                 type="array",
*                 @SWG\Items(
*                     type="object",
*                     required={"user_id"},
*                     @SWG\Property(
*                         property="user_id",
*                         type="integer",
*                         example=1,
*                         description="可有可无的字段描述",
*                     ),
*                     @SWG\Property(
*                         property="username",
*                         type="string",
*                         example="三脚猫",
*                     ),
*                 ),
*             ),
*         ),
*         @SWG\Schema(ref="#/definitions/paginate"),
*     },
* ),

• OAuth 公共使用 (Parameter.php)

 * *********************************token
 * @SWG\Parameter(
 *   parameter="Authorization",
 *   name="Authorization",
 *   description="oauth token",
 *   type="string",
 *   format="string",
 *   in="header",
 *   required=true
 * ),
 * *********************************end

• Success 公共使用 (Definitions.php)

 * ************************************  success  **********************************
 * @SWG\Definition(
 *     definition="success",
 *     type="object",
 *     required={"status","code","message"},
 *     allOf={
 *          @SWG\Schema(
 *              @SWG\Property(
 *                  property="status",
 *                  type="boolean",
 *                  example="true",
 *                  description="请求状态",
 *              ),
 *              @SWG\Property(
 *                  property="code",
 *                  type="integer",
 *                  example=200,
 *                  description="状态码",
 *              ),
 *              @SWG\Property(
 *                  property="message",
 *                  type="string",
 *                  example="操作成功",
 *                  description="状态语义",
 *              ),
 *              @SWG\Property(
 *                  property="data",
 *                  type="string",
 *                  example="[]",
 *                  description="无数据返回",
 *              ),
 *          )
 *     },
 * ),
 * *********************************************************end

• 分页 公共使用 (Definitions.php # 引入语法 @SWG\Schema(ref="#/definitions/paginate"),)

 * ************************************  分页  **********************************
 * @SWG\Definition(
 *      definition="paginate",
 *      type="object",
 *      required={"links","meta"},
 *      @SWG\Property(
 *          property="links",
 *          type="object",
 *          @SWG\Property(
 *              property="first",
 *              type="string",
 *              example="http://www.xxx.com/api/xxxxx?page=1",
 *          ),
 *          @SWG\Property(
 *              property="last",
 *              type="string",
 *              example="http://www.xxx.com/api/xxxxx?page=1",
 *          ),
 *          @SWG\Property(
 *              property="prev",
 *              type="string",
 *              example="http://www.xxx.com/api/xxxxx?page=1",
 *          ),
 *          @SWG\Property(
 *              property="next",
 *              type="string",
 *              example="http://www.xxx.com/api/xxxxx?page=1",
 *          ),
 *      ),
 *      @SWG\Property(
 *          property="meta",
 *          type="object",
 *          @SWG\Property(
 *              property="current_page",
 *              type="integer",
 *              example=1,
 *          ),
 *          @SWG\Property(
 *              property="from",
 *              type="integer",
 *              example=2,
 *          ),
 *          @SWG\Property(
 *              property="last_page",
 *              type="integer",
 *              example=4,
 *          ),
 *          @SWG\Property(
 *              property="path",
 *              type="string",
 *              example="http://www.xxx.com/api/xxxxx?page=1",
 *          ),
 *          @SWG\Property(
 *              property="per_page",
 *              type="integer",
 *              example="18",
 *          ),
 *          @SWG\Property(
 *              property="to",
 *              type="integer",
 *              example=18,
 *          ),
 *          @SWG\Property(
 *              property="total",
 *              type="integer",
 *              example=5,
 *          ),
 *      ),
 * ),
 * *********************************************************end

解释Swagger参数

/**
* 这是一个资源控制器的Show方法 .
* @param  int $id
* @return \App\Http\Resources\Product\GoodsShowResource
*
* @SWG\Get(
*    path="/goodsNorm/{id}",  //路由名称
*    tags={"Product"},  //标签名称 eg: Http/Controller/Document/Product 里面放接口文档Responses集合
*    operationId="goods-norm",  //用于识别操作url地址栏中显示
*    summary="获取商品",  //外面标题
*    description="获取单个商品详细数据",  //里面详细标题
*    consumes={"application/json"},    //Mime类型常用的就这两种 application/x-www-form-urlencoded
*    @SWG\Parameter(ref="#/parameters/Authorization"),  //可理解为参数定义路径/Document/parameters.php
*    @SWG\Parameter(ref="#/parameters/common-id"),      //同上
*    @SWG\Response(                                     //必填的响应对象
*        response=200,                                  //响应的状态码
*        description="成功获单个商品",                   //响应后的提示
*        @SWG\Schema(ref="#/definitions/goods-norm")    //响应成功后的参数示例
*    )
*    @SWG\Response(
*        response=404,
*        description="没有找到您要详细参数的数据",
*    )
* )
*/
public function show($id){
      //@#$%^&**  业务逻辑层

      //API资源返回json数据格式 （详情见Laravel5.5手册 Eloquent ORM的API资源）
      return new GoodsNormResource($detail);
}

解释参数构造->Parameter.php

@SWG\Parameter(ref="#/parameters/Authorization")
文件夹路径：app/Http/Controller/Document/parameters.php

返回json语法定义->definitions.php

@SWG\Schema(ref="#/definitions/goods-norm")
文件夹路径：app/Http/Controller/Document/definitions.php

Definition @SWG\Schema(ref="#/definitions/json-json"),

• json下放json

 * @SWG\Definition(
 *     definition="json-json",
 *     required={"json"},
 *     type="object",
 *     allOf={
 *          @SWG\Schema(
 *              @SWG\Property(
 *                  property="json",
 *                  type="object",
 *                  description="json字段",
 *                  required={"name"},
 *                  @SWG\Property(
 *                       property="name",
 *                       type="string",
 *                       example="三脚猫",
 *                       description="用户名",
 *                  ),
 *              ),
 *          ),
 *     },
 * ),
 ************************************  Demo  **********************************
{
  "json":{
    "name":"三脚猫",
  }
}

• json下放数组

 * @SWG\Definition(
 *     definition="json-array",
 *     required={"json"},
 *     type="object",
 *     allOf={
 *          @SWG\Schema(
 *              required={"json"},
 *              @SWG\Property(
 *                  property="json",
 *                  type="array",
 *                  description="json字段",
 *                  required={"name"},
 *                  @SWG\Items(
 *                      @SWG\Property(
 *                          property="name",
 *                          type="string",
 *                          example="三脚猫",
 *                          description="用户名",
 *                      ),
 *                  ),
 *              ),
 *          ),
 *     },
 * ),
 ************************************  Demo  **********************************
{
  "json":{[
    "name":"三脚猫"
  ],[
    "name":"三脚猫"
  ],}
}

以上都是blog里复制出来的，有些文字不必在意，知道是代表的什么意思就好啦。有问题留言~