spring boot 整合swagger

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

一、添加依赖

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

</dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

</dependency>

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

二、添加注解

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

springbootStarter.java

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

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也扫描进去。

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只是一个调接口的工具而已。如果不是敏捷开发的模式，绝对不能省接口设计，接口文档，单元测试的功夫。不要拿工具做偷懒的接口哦。

Post Views: 823

xie4ever's blog

spring boot 整合swagger

一、添加依赖