项目中swagger-ui使用历程

栏目: 后端 · 发布时间: 5年前

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

解决办法:这里就需要知道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令牌得参数,看图

项目中swagger-ui使用历程

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

项目中swagger-ui使用历程

项目中swagger-ui使用历程

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

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

项目中swagger-ui使用历程

项目中swagger-ui使用历程 微信打赏

项目中swagger-ui使用历程 支付宝打赏

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


以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持 码农网

查看所有标签

猜你喜欢:

本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们

创新公司

创新公司

[美]艾德·卡特姆、埃米·华莱士 / 靳婷婷 / 中信出版社 / 2015-2 / 49.00元

●《玩具总动员》《海底总动员》《机器人瓦力》《飞屋环游记》等14部脍炙人口的动画长片, 近30次奥斯卡奖, 7部奥斯卡最佳动画长片,7次金球奖; ●几乎每一部电影一上映都位居票房榜首,所有电影都曾进入影史票房总榜前50,每一部电影都是商业与艺术的双赢。 ●即便新兴动画公司不断涌现,皮克斯始终保持动画界的王者之位,这一切背后的秘密就在于:不断推动创新的创意管理方式。 你可以从本书......一起来看看 《创新公司》 这本书的介绍吧!

HTML 压缩/解压工具
HTML 压缩/解压工具

在线压缩/解压 HTML 代码

CSS 压缩/解压工具
CSS 压缩/解压工具

在线压缩/解压 CSS 代码