自定义swagger-ui

swagger-ui

采用Vue+element-ui构建的swagger-ui，Github地址：

https://github.com/yaojunguang/swagger-ui

介绍

在日常开发中，接口文档维护一直是项目管理中的头疼的问题，还有就是单元测试、接口测试等。swagger是我极具推崇的开发辅助工具，很好的解决了上诉的这些问题

在移动端开发过程中module生成也一直是费力而麻烦的事情(java对android可公共module包解决)，以前也做过一个用java class反射生成 swift module的小工具

以前一直在使用springfox-swagger-ui作为swagger的ui展示，但是在实际使用过程中有诸多的不满意的地方，遂结合自己的实际需求，采用Vue+element-ui自行开发了这个项目

主要的功能特色如下：

0、概览

1、采用左右布局，便于充分利用屏幕空间

2、左侧方案按tag分组，便于集中管理

3、左侧导航栏支持宽度调整，调整结果保存到cookie

4、右侧项目部分tab化管理，便于打开多个

5、参数可分组，默认以描述中以"【公共参数】"开头的放入到公共参数中（具体原因后续有机会在介绍），该函数独有参数放入专有参数并默认展开

6、返回实体结果全部列举，支持一键转化为swift和java，module代码格式化高亮处理，一键复制

7、在线直接调用测试

8、运行结果格式化高亮展示

约定

该swagger是根据我在日常开发中的一些个人需求自行定制的swagger-ui,其中涉及到诸多约定

1、返回结果为JSON

2、不根据http的状态码判断内部逻辑处理是否正确，而是通过外包一个包装类来返回结果

3、返回结果需要指明类型，这样swagger才能识别，如下面的例子

@ResponseBody

@ApiOperation(value = "喜欢的列表", notes = "喜欢-列表")

@RequestMapping(value = "", method = RequestMethod.GET)

public RespEntity> findByPage(

        @ApiParam(value = "页码")

        @RequestParam(name = "page") int page,

        @ApiParam(value = "类型，0酒单，1文章，2视频")

        @RequestParam(name = "itemType") int itemType,

        BaseReq req) {

    RespEntity> respEntity = RespEntity.One(req);

    try {

        .....

    } catch (Exception ex) {

        error(ex, respEntity);

    }

    return respEntity;

}

4、为了便于维护管理接口分组，Controller的tag都已数字开头，便于自动排序，如下：

@RestController

@Api(tags = {"05、喜欢"})

@RequestMapping(value = "/v8/love")

public class LoveControllerV8 extends BaseControllerV8 {

  .....

}

5、该项目建立的目的是为了方便交流维护(要有注释)，所涉及的实体对象均需要按照swagger注解要求填写如下返回实体

对于@ApiModel的注解，不要使用value属性，否者会使类名不一直

@Data

@ApiModel(description = "CartUiEntity")

public class CartUiEntity {

    @ApiModelProperty("地址编号")

    private int addressId = 0;

    @ApiModelProperty("收件人")

    private String recipient;

    @ApiModelProperty("电话号码")

    private String mobile;

    @ApiModelProperty("详细地址")

    private String addressDetail;

}

测试运行

测试运行中项目中包含了一个swagger文档sample文件，可自行替换（src/assets/api-docs.json）

# 依赖安装

npm install

# 测试运行

npm run dev

# 生产打包

npm run build:prod

打包为JAR

打包过程默认为npm run build:prod.会自动切换为包所在的本地环境

# mvn生产打包发布

mvn install

安装

前置

安装好swagger2，并按默认配置，不需要其他第三方的swagger-ui，只需要加入默认依赖

    io.springfox

    springfox-swagger2

    ${swagger.version}

jar复制安装

复制生成的swagger-ui-0.4.jar 到你的工程下，添加依赖即可

    com.smarthito

    swagger-ui

    0.4

    system

    ${pom.basedir}/src/main/libs/swagger-ui-0.4.jar

maven依赖

    com.smarthito

    swagger-ui

    0.4

访问

默认页面 /swagger-ui.html

http://:/swagger-ui.html

TODO:

支持一键生成移动端调用代码

作为公开库，不同公司的调用模块不尽相同，大家可根据实际需求修改

支持枚举对象的导出

实际开发中，状态变量的枚举一直是前后端沟通的问题，这个部分的导出需要一些开发约定，在未想好对开发过程无干扰的情况下暂时搁置（java 采用class反射可实现，但对开源项目安全性角度不想采用）。

后语：

该项目对于采用swagger注释完善度要求极高，这样可以使整个工具呈现完美状态，这个部分也有一些其它的自定义小工具，后续会再分享，如：数据库表生成module的groovy schema等