网站产品页如何做优化,淘宝网站图片维护怎么做,网站建设公司知识,搜搜提交网站入口问题描述
在使用springboot开发web项目时#xff0c;用到了swagger框架#xff0c;来生成web api文档。但是其中有一项是举例说明参数的结构#xff0c;如下图#xff1a;但是#xff0c;这个功能真的是非常方便#xff0c;因为可以让前端开发人员第一时间得知参数的内部…问题描述
在使用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格式,requiredtrue) 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框架的一点看法和总结如有疑问欢迎文末留言。
