项目中swagger-ui使用历程

现在大家做的 java 项目基本上都是前后端分离的,后端只提供api接口即可,和前端交互的时候都是用json,然后在这个过程中就会出现一个问题,前后端交互的时候就约定接口的数据格式,然后我们现在的项目前端还是外包给公司外的人做的,给外包提供api接口数据的时候沟通起来非常麻烦,而且文档写的不完整还要被外包说,主要 程序员 都讨厌写文档,但是不写接口文档肯定要被前端开发喷死.

这个时候swagger-ui就提现了强大之处了,自动生成文档,不仅可以方便自己写完接口后调试,也可以自动生成文档给前端人员调试,还真挺好用的,但是刚开始用这个,还是遇到了一点点小问题的,下面就说下用的过程中遇到的问题,已经解决办法.

不过你可能要问了,你这一上来就说遇到的问题,我看了一脸懵逼啊,我现在连swagger怎么用的,能干嘛,以及怎么让它在项目里跑起来,你一个都没说,直接就说问题,你考虑过读者的感受吗,哈哈,其实我一开始也想写篇整合swagger和springboot的博客,后来发现公司已经有人写了,https://blog.yayuanzi.com/24317.html,这是对应的链接地址,想看整合的,直接看这篇吧,我这里就不重复了,直接说遇到的问题吧.

问题1.因为项目是使用前后端分离的,所以session啊什么的肯定就不能用了,那我要怎么知道用户的登录状态呢,目前普遍的做法是用token,那么问题就来了,token是放在header里的,使用swagger调用接口的时候没有传header的地方,看图

解决办法:这里就需要知道swagger的用法了,网上搜了一下,大概意思就是添加一个全局的操作,就是所有的接口都增加一个header的参数,代码如下.

<code lang=’java’>

//添加header参数token
ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<>();
tokenPar.name("token")
        .description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
pars.add(tokenPar.build());

return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        //为当前包路径
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.regex("/api/.*"))
        .build().globalOperationParameters(pars);

</code>

添加之后再看页面就会看到一个token令牌得参数,看图

问题2:swagger返回数据类型都是一个空得大括号,看不到具体得返回类型,这个问题导致了前端开发人员看不到返回数据得格式,或者说看不到具体返回了啥,后来检查代码发现原来是自己的问题,swagger是根据返回数据的类型来生成这个对应的example value的,然后我们的代码里写的返回类型都是一个ResultVO<T>,在具体的方法返回值里没有指明这个泛型在当前具体是什么类型,导致swagger-ui也不知道是什么,所有就放了一个空的大括号在那里,找到问题了那就开始修改代码了,其实只要把返回值的类型从ResultVO改成ResultVO<Map<String, List<TradeApiVO>>>就可以了,然后再看效果就是后面那个图片的效果了.

好了,以上就是我在使用过程中遇到的一些问题及解决办法,有兴趣的可以一起探讨深入学习.

转载时请注明出处及相应链接，本文永久地址：https://blog.yayuanzi.com/24605.html

微信打赏

支付宝打赏

感谢您对作者joy1的打赏，我们会更加努力！    如果您想成为作者，请点我