swagger升职记

背景

某天小伙伴找我反馈目前他想要在api请求的时候限制参数【比如一个查询实体有20个条件 他现在只想要暴露2个条件】

每次都要把一对参数写在controller上~

e24c02d1821b7e8969b6f7fce76da1ccb7b.jpg

问我有什么好的办法!

过程

看到这种写法就特别奇怪 以前写的好好地单参数写法为何到了这边突然又变成了多个参数?

这样需要手动塞好多参数 为什么不定义成一个新的对象呢?这个对象中只能包含特定的你想要暴露出去的参数呢???最终通过bean copy工具【比如orika】转变成下一层查询所需要的对象

我转达了这个疑问~

小伙伴表示说因为单对象参数在swagger当前版本上不能展示参数

如下图

72a07905a8257fe3cf15950f84075e8fc8a.jpg

由于swagger不能展示===》提供多个参数===》需要一个快速collect多个参数到对象的方法

这也是典型的IT人的思路 我因为要解决这个问题 但是前提是解决另一个问题【递归下去】===》万一解决不了就是OOM了 ^_^

不过本质上我们确实需要多参数么??? 而且swagger上很明显带来了dataSchema了 只是不知道何故没有暂时而已

分析

带着这个疑问我们看了一下post请求

ac14658e1a03ce27872ec6e7ad0c0dfee79.jpg

好像确实在swagger-2.2.2的版本下面出现了get不可以展示schema

看看对应的swagger文件呢

8e467e747ab6d0604f6ba0a482560453bbe.jpg

看来有可能是swagger-ui的bug【或者feature?】

于是我们考虑升级呗~~~

f5b82d6bdd2625b7e34541ce5336319d5af.jpg

我们目前使用2.2.2 确实很久远了~考虑一下升级

选择流行度较高和发布日期较近的2.8.0~为何不选择2.9.2???

因为Guava呗【目前我们还是用18.0】

4a0a2bb39aae91aeb0440683a9e37365701.jpg

当然也是升级了之后报错了呗~

于是我们选择了2.8.0 bingo~升级完成后注意清除缓存

edb0de2f5ba645c4d653d9b79b7bd289a2b.jpg

问题

升级完成之后发觉如下问题

基于swagger2的离线pdf和html文档生成 开始报错了……

https://github.com/swagger-api/swagger-parser/issues/442

嗨……又得升级 对应的swaggerparse升级

这个时候发现 swagger2markup在2016年底不维护了 同时出现了新的构件

0b2eb3de8834f807f14049cf07b6bfa0f44.jpg

嗨~还得升级 一堆搞完之后终于可以了~

彩蛋

目前我们使用了jwt 某些应用的api需要在头上增加token以便来校验授权

为了解决小伙伴在swagger不能测试的苦恼 我们增加了对应的头如下

当开启jwt之后swagger-ui上将增加对应的头

c9248f251b32f8cf3120eee03311483cffc.jpg