问题描述

在使用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;}@ApiModelclass 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;}@ApiModelclass 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框架的一点看法和总结，如有疑问，欢迎文末留言。

Swagger使用————接口参数注解的使用缺陷相关推荐

swagger学习日记1 swagger测试接口时传入参数的类型问题
问题现象: 今天在学习swagger做接口api说明的时候,出现了一个一直解决不了的问题,而且网上搜了很久,都找不到任何相似的问题和解决方法: 当用swagger测试一个需要传入(Integer数据类 ...
aop+注解实现对实体类的字段校验_SpringBoot实现通用的接口参数校验
来自:掘金,作者:cipher 链接:https://juejin.im/post/5af3c25b5188253064651c76 原文链接:http://www.ciphermagic.cn/sp ...
使用自定义注解实现接口参数校验
1.前言在接口的开发中,我们有时会想让某个接口只可以被特定的人(来源)请求,那么就需要在服务端对请求参数做校验. 这种情况我们可以使用interceptor来统一进行参数校验,但是如果很多个接口,有 ...
swagger参数注解，后台使用@RequestBody注解的实体类，但只需要传实体类中的一个属性
一开始是这个样子的 @ApiOperation(value = "删除用户", notes = "根据用户名删除指定用户", httpMethod = &quo ...
swagger 接口参数顺序_Swagger常用参数用法 - mao2080 - 博客园
别提示:本人博客部分有参考网络其他博客,但均是本人亲手编写过并验证通过.如发现博客有错误,请及时提出以免误导其他人,谢谢!欢迎转载,但记得标明文章出处: http://www.cnblogs.com/ ...
还在用Swagger生成接口文档？我推荐你试试它.....
点击上方"方志朋",选择"设为星标" 回复"666"获取新整理的面试文章 JApiDocs是一个无需额外注解.开箱即用的SpringBoot ...
idea swagger生成接口文档_spring boot集成Swagger-UI接口文档
本文介绍如何用spring boot集成Swagger-UI,实现项目在线接口文档一.Swagger-UI简介 Swagger是一个Restful风格接口的文档在线自动生成和测试的框架官网对Swa ...
实体类接口_spring-boot-route（五）整合Swagger生成接口文档
目前,大多数公司都采用了前后端分离的开发模式,为了解决前后端人员的沟通问题,后端人员在开发接口的时候会选择使用swagger2来生成对应的接口文档,swagger2提供了强大的页面调试功能,这样可以有 ...
springboot 中文文档_还在用 Swagger生成接口文档？我推荐你试试它
JApiDocs是一个无需额外注解.开箱即用的SpringBoot接口文档生成工具. 编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又不得不做的事情,我们都不喜欢写文档,但除非项目前后 ...

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

问题描述

问题原因

吐槽一下

Swagger使用————接口参数注解的使用缺陷相关推荐

最新文章

热门文章