Swagger使用————接口参数注解的使用缺陷

问题描述

在使用springboot开发web项目时，用到了swagger框架，来生成web api文档。但是其中有一项是举例说明参数的结构，如下图：

但是，这个功能真的是非常方便，因为可以让前端开发人员第一时间得知参数的内部结构是什么样的，这尤其适用于那些json体结构的参数。网上的例子都是这样的：

但是，我无论如何都弄不出来这个样子，前前后后研究了有好几个小时。

终于找出了问题。

问题原因

网上的api接口中，几乎全是传入一个完整的Java Bean对象，而不是传JsonObject对象。

我的代码是这样：

    @ApiOperation(value = "添加景区下的特价门票", notes = "{\"scenicIdArr\" : [53361,53356]}")
    @PostMapping(value = "/special_price/add")
    public JSONObject addSpecialPrice(@RequestBody JSONObject scenicIdArr) {

        return sprSvc.addSpecialPrice(scenicIdArr);
    }

别人的代码是这样：

    @ApiOperation("更改用户信息")
    @PostMapping("/updateUserInfo")
    public int updateUserInfo(@RequestBody @ApiParam(name="用户对象",value="传入json格式",required=true) User user){
        int num = userService.updateUserInfo(user);
        return num;
    }

经过比较，很容易就发现了问题，我的接口中的参数是无法得知内部数据结构的JSONObject类型，而别人的参数是一个已知其内部数据结构的User对象。

既然知道了原因，那我也将接口进行了一些修改：

创建一个符合我业务要求的数据结构实体类，然后将这个实体类作为参数传入接口中：

    @ApiOperation(value = "添加景区下的特价门票", notes = "{\"scenicIdArr\" : [53361,53356]}")
    @PostMapping(value = "/special_price/add")
    public JSONObject addSpecialPrice(@RequestBody ScenicIdArr scenicIdArr) {

        return null;
    }
    @ApiModel
    class ScenicIdArr {
        @ApiModelProperty(value = "景区id数组")
        int[] scenicIdArr;
    }

上述代码中，我定义了一个成员内部类，并将实体类以@ApiModel进行注解。效果如下：

呵呵，没有一丁点效果！我陷入了沉思... ...

于是我大胆的猜想：swagger框架可能是自动调用了get或set方法，并完成页面渲染。

于是我又修改了代码：

@ApiOperation(value = "添加景区下的特价门票", notes = "{\"scenicIdArr\" : [53361,53356]}")
    @PostMapping(value = "/special_price/add")
    public JSONObject addSpecialPrice(@RequestBody ScenicIdArr scenicIdArr) {

        return null;
    }
    @ApiModel
    class ScenicIdArr {
        @ApiModelProperty(value = "景区id数组")
        int[] scenicIdArr;

        public int[] getScenicIdArr() {
            return scenicIdArr;
        }
    }

我加了一个get方法，来获取实体类中的属性，看一下效果：

上图中可以看到，不论是整体的实体类结构，还是字段上的注释“景区id数组”都很好的显示了出来。这样，我们在页面点击小黄框的时候，就可以将数据自动的加载到参数填写的白框内。

这样，我们省去了手动书写结构和key值的过程，而只需要我们输入具体的value值即可。

由于本篇博客并不是教你如何使用spring-boot-starter-swagger自动依赖配置模块中的各种注解如何使用，因此，此处只是简单解析了一下接口参数的模板生成方式。

但是，题目中既然提到了这个功能的缺陷，就不得不回过头来吐槽一下这个破JB玩意儿！

吐槽一下

这个在小黄框显示对外接口参数结构的功能真的应该说是非常实用的一个功能，我并不知道这个功能具体的名称是什么，暂且就称它为“参数样例功能”。

为什么说这个功能非常实用？

首先，书写简便。REST接口风格的参数多以json结构体传输数据，而这样一个自动生成结构体的功能，可以为我们免去书写大量括号、冒号、逗号、引号、空格等json体的必须元素，而且自动排版，避免手写出错，达到零错误。在真正通过页面的api接口测试的时候，只需要简单输入几个value值就可以“try it out”了，着实提高了不少效率。

其次，方便前端开发。我们都知道，不论是传入JavaBean对象，还是传入没有在后端强制类型约束的Json字符串，前端调用controller中的接口时，仅仅是传入一个key-value的结构，才不会管你什么JavaBean。对于springboot，其一系列内嵌的HttpMessageConverter会将json结构转化成对应的JavaBean，再交给Controller。前端开发人员甚至可以将小黄框内的内容，直接拷贝过来，稍作修改（value赋值）即可完成对后端接口对接的全部编码。

第三，覆盖了其他部分注解。个人认为，swagger中的注解关于参数注释方面，有些重复，这一点不做展开讨论，且仅仅是个人观点，可以参考官方api文档体会一下。另外关于response一类的注解，完全没有必要。返回值是什么结构的，完全可以通过“try it out”调用一次接口即可了解到。估计swagger开发团队考虑到功能的完整性，或者在后端由于某种原因导致接口不可用而做的一种补足方案（比如，数据库中暂无数据等原因）。

虽然这个功能实用，但是依然存在一个很别扭的情况。

那就是，我们不得不因为要在“参数样例功能”中展示我们的参数结构而创建一个Java Bean。不论这个Java Bean在后台逻辑中有无实际意义。

就比方说我之前的那个接口：

    @ApiOperation(value = "添加景区下的特价门票", notes = "{\"scenicIdArr\" : [53361,53356]}")
    @PostMapping(value = "/special_price/add")
    public JSONObject addSpecialPrice(@RequestBody JSONObject scenicIdArr)

我需要拿到一个有景区id组成的json体的数据结构，然后跑到service中去处理，可能我的这种api结构并不规范，但是不可能不存在这样一种情况：仅仅规定一个json结构，而不是Java Bean来作为参数进行处理。（抱歉，最近在看《Thinking In Java》句子写起来有那么一点模仿布鲁斯埃克尔的腔调）

我查找了很多资料，包括官方的API说明，并没有很好解决方案。于是，才有了后面的成员内部类的出现。但是这种代码除了方便测试以外完全没有实际意义。如果为每个以json结构体作为参数的接口另起一个class文件去明确传入参数的结构，就显得有些愚蠢。它会使你的代码非常的臃肿和凌乱。

这就是我说的swagger的这个缺陷，以纯json结构体作为参数的接口，无法实现非常重要的“参数样例功能”。

综上，就是我对swagger框架的一点看法和总结，如有疑问，欢迎文末留言。