spring boot 整合swagger

spring boot整合swagger非常简单,但是依然有美中不足的地方

 

一、添加依赖

目前最新版本是2.6.1,但是目前新版swagger支持中文有些小问题。旧版本的(如2.2.2)似乎没有这种问题,但是界面没那么美观。这个问题将在后面提到。

二、添加注解

1.使用@EnableSwagger2注解修饰启动类

springbootStarter.java

2.使用@Api修饰Controller

和spring mvc中一样,用@Api注解修饰需要进行展示的Controller。

testController.java

3.多出Basic Error Controller选项卡的问题

因为我们添加了swagger-ui的依赖,swagger的ui界面已经内置在了依赖中,访问http://localhost:8080/swagger-ui.html就可以看到熟悉的界面。但是会出现这样一个问题:莫名其妙地多出一个Basic Error Controller的选项卡(其实是swagger内置的一个测试接口)。

1

如果要去掉这个选项卡,可以采取以下方法:

参考:http://stackoverflow.com/questions/32941917/remove-basic-error-controller-in-springfox-swaggerui

我们可以写一个swagger的配置类,指定swagger插件扫描的范围,从而避免把Basic Error Controller也扫描进去。

这里需要注意:

(1)@Configuration的功能是声明这个文件是spring的配置文件。在配置类上一定要用@Configuration注解修饰,并且放置在启动类可以扫描到的地方,才能被启动类扫描到。

(2)config方法上一定要用@Bean注解修饰,否则无法启用配置。(基本上和以前spring mvc中的swaggerConfig的配置是一样的)

在加入了swagger配置类之后,这个Basic Error Controller就消失了。

1

三、swagger一点关于中文支持的小问题

如果在controller中把@Api注解中的tags属性设成中文

swagger-ui就会出现中文路径的问题

1

新版的swagger基本上都存在这个问题。后来我测试了2.2.2版本的swagger依赖,并没有出现这个问题,所以稍旧一些的版本使用起来也许更顺手哦。

但是我感觉旧版的swagger界面不这么美观,功能似乎也有欠缺。所以我个人认为tags这里不要使用中文就可以了。

四、总结

最后要清楚,swagger只是一个调接口的工具而已。如果不是敏捷开发的模式,绝对不能省接口设计,接口文档,单元测试的功夫。不要拿工具做偷懒的接口哦。

发表评论

电子邮件地址不会被公开。 必填项已用*标注