spring boot 整合swagger
spring boot整合swagger非常简单,但是依然有美中不足的地方
一、添加依赖
1 2 3 4 5 6 7 8 9 10 11 12 |
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency> |
目前最新版本是2.6.1,但是目前新版swagger支持中文有些小问题。旧版本的(如2.2.2)似乎没有这种问题,但是界面没那么美观。这个问题将在后面提到。
二、添加注解
1.使用@EnableSwagger2注解修饰启动类
springbootStarter.java
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
package springboot; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import springfox.documentation.swagger2.annotations.EnableSwagger2; @SpringBootApplication @EnableSwagger2 //开启swagger支持 public class springbootStarter { public static void main(String[] args) throws Exception { SpringApplication.run(springbootStarter.class, args); } } |
2.使用@Api修饰Controller
和spring mvc中一样,用@Api注解修饰需要进行展示的Controller。
testController.java
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
package springboot.controller; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.ResponseBody; import org.springframework.web.bind.annotation.RestController; import io.swagger.annotations.Api; import springboot.pojo.ReturnPojo; @Api @RestController @RequestMapping("/test") public class testController { ..... } |
3.多出Basic Error Controller选项卡的问题
因为我们添加了swagger-ui的依赖,swagger的ui界面已经内置在了依赖中,访问http://localhost:8080/swagger-ui.html就可以看到熟悉的界面。但是会出现这样一个问题:莫名其妙地多出一个Basic Error Controller的选项卡(其实是swagger内置的一个测试接口)。
如果要去掉这个选项卡,可以采取以下方法:
参考:http://stackoverflow.com/questions/32941917/remove-basic-error-controller-in-springfox-swaggerui
我们可以写一个swagger的配置类,指定swagger插件扫描的范围,从而避免把Basic Error Controller也扫描进去。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
package springboot.application; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; @Configuration public class swaggerConfig { @Bean public Docket config() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("springboot.controller")) .build(); } } |
这里需要注意:
(1)@Configuration的功能是声明这个文件是spring的配置文件。在配置类上一定要用@Configuration注解修饰,并且放置在启动类可以扫描到的地方,才能被启动类扫描到。
(2)config方法上一定要用@Bean注解修饰,否则无法启用配置。(基本上和以前spring mvc中的swaggerConfig的配置是一样的)
在加入了swagger配置类之后,这个Basic Error Controller就消失了。
三、swagger一点关于中文支持的小问题
如果在controller中把@Api注解中的tags属性设成中文
1 |
@Api(tags = {"测试相关"}) |
swagger-ui就会出现中文路径的问题
新版的swagger基本上都存在这个问题。后来我测试了2.2.2版本的swagger依赖,并没有出现这个问题,所以稍旧一些的版本使用起来也许更顺手哦。
但是我感觉旧版的swagger界面不这么美观,功能似乎也有欠缺。所以我个人认为tags这里不要使用中文就可以了。
四、总结
最后要清楚,swagger只是一个调接口的工具而已。如果不是敏捷开发的模式,绝对不能省接口设计,接口文档,单元测试的功夫。不要拿工具做偷懒的接口哦。