美文网首页
Swagger框架 API文档速成

Swagger框架 API文档速成

作者: Super三脚猫 | 来源:发表于2018-03-15 17:03 被阅读0次

    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

    <?php
/**
 ************************************  token  **********************************
 * @SWG\Parameter(
 *   parameter="Authorization",      //Authorization 名称，用来在方法注释寻找
 *   name="Authorization",          //千万别用汉字，如果在传id的时候会解析错误
 *   description="oauth token",    //inuput输入框描述
 *   type="string",     //数据类型 integer string boolean password模糊输入 float数字 byte编码的字符base64
 *   format="string",  //同上，不知道干嘛的，写上错不了- -
 *   in="header",     //
 *   required=true  //输入框不能为空
 * ),
 ************************************  common  **********************************
 * @SWG\Parameter(
 *    parameter="common-id",
 *    name="id",
 *    in="path",
 *    type="integer",
 *    description="ID",
 *    required=true
 * ),

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

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

    <?php
/**
 * @SWG\Definition(
 *      definition="201",
 *      required={"message"},
 *      @SWG\Property(
 *          property="message",
 *          type="string",
 *          example="创建成功"
 *      )
 * ),
 ************************************  204  **********************************
 * @SWG\Definition(
 *      definition="204",
 *      required={"message"},
 *      @SWG\Property(
 *          property="message",
 *          type="string",
 *          example="删除成功"
 *      )
 * ),

    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里复制出来的，有些文字不必在意，知道是代表的什么意思就好啦。有问题留言~

    相关文章

      网友评论

          本文标题：Swagger框架 API文档速成

          本文链接：https://www.haomeiwen.com/subject/uubhqftx.html

          延伸阅读

          深度阅读

          • 您也可以注册成为美文阅读网的作者，发表您的原创作品、分享您的心情！

          栏目导航

          热点阅读

          关于我们|服务条款|联系我们|Swagger框架 API文档速成|投稿指南|网站地图|RSS订阅|排版工具|手机版

          提供经典美文摘抄,优美散文欣赏,现代诗歌精选,短篇小说,心情随笔,表白情书范文,故事会在线阅读欣赏

          Copyright © 2014-2023 Haomeiwen.com All Rights Reserved. 好美文阅读网 版权所有

          备案信息：桂公网安备 45052102000051号 · 桂ICP备13007215号-3

          本站所收录作品、热点评论等信息部分来源互联网，目的只是为了系统归纳学习和传递资讯

          所有作品版权归原创作者所有，与本站立场无关，如不慎侵犯了你的权益，请联系我们告知，我们将做删除处理！