Spring boot 整合Swagger

推荐一个博客,讲的不错

http://www.cnblogs.com/softidea/p/6251249.html

前言

引用:http://blog.csdn.net/wangnan9279/article/details/44541665

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

个人的学习及使用过程(最下边有完整的代码,过程是我的经验,可以省略不看)

1 学习

在网上寻找好多的demo来学习,结果都无法达到自己的要求,这个

出来了,然后这个

又丢失了,真是丢了东墙失了西墙,总之就是没办法达到自己的要求,经过6个多小时的奋斗,终于整出来符合自己要求的东西了,下面我讲一下我的学习过程.

1.1 初学demo

pom 文件(这个pom文件没有出什么大问题,全局都使用这个pom)

<!-- Spring Boot 启动父依赖 核心模块，包括自动配置支持、日志和YAML-->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.5.1.RELEASE</version>
</parent>

<dependencies>

<!-- Spring Boot web依赖 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!--SeaSwagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>

<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>

<!-- 实现spring boot的热部署 -->
<dependency>
<!--Spring 官方提供的热部署插件 -->
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<optional>true</optional>
</dependency>

</dependencies>

<build>

<finalName>SpringBoot_Study</finalName>

<plugins>

<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<dependencies>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>springloaded</artifactId>
<version>1.2.6.RELEASE</version>
</dependency>
</dependencies>
</plugin>

</plugins>

</build>

启动类

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2 // 注意这个地方,其实是没用的,(原因不知道)
public class SwaggerApplication {

public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class);
}
}

测试使用的Controller(这个类也没变化,全局使用)

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;

/**
* @Api：用在类上，说明该类的作用
* @ApiOperation：用在方法上，说明方法的作用
* @ApiImplicitParams：用在方法上包含一组参数说明
* @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 paramType：参数放在哪个地方
*              header-->请求参数的获取：@RequestHeader
*              query-->请求参数的获取：@RequestParam
*              path（用于restful接口）-->请求参数的获取：@PathVariable
*              body（不常用）
*              form（不常用）
*              name：参数名
*              dataType：参数类型
*              required：参数是否必须传
*              value：参数的意思
*              defaultValue：参数的默认值
*              httpMethod:设置请求方式
* @ApiResponses：用于表示一组响应
* @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400
*              message：信息，例如"请求参数没填好"
*              response：抛出异常的类
* @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
* @ApiModelProperty：描述一个model的属性
*/
@Controller
@Api("http相关接口")
public class SwaggerDemoController {

@ApiOperation(value = "Swagger学习测试接口", notes = "根据url的id来指定删除用户",httpMethod = "POST")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
@RequestMapping("/swagger")
public String swaggerStudy() {
return "hello swagger";
}
}

配置类(这个变化的很大)

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2 // 请注意这个地方
public class SwaggerConfig {

@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select() // 这个地方以及下边三行
.apis(RequestHandlerSelectors.basePackage("com.qhong.web"))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建Restful Api")
.version("1.0")
.build();
}

}

重点变化过程

我按照上边的配置类进行配置,然后启动了项目,结果想要的api接口说明出现了,但是我在配置类里面设置的title/version/等内容没有出现,继续变化

配置类二次变化

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@Configuration // 这次变化的地方
public class SwaggerConfig {

@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.qhong.web"))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建Restful Api")
.version("1.0")
.build();
}

}

看到代码中变化的地方了吧,添加上这个注解之后,结果还是不行,页面出现了配置类中的内容,但是api接口说明文档不见了,然后接着在变化

配置类三次变化

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@Configuration
public class SwaggerConfig {

@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
/*.select() // 变化的地方
.apis(RequestHandlerSelectors.basePackage("com.qhong.web"))
.paths(PathSelectors.any())
.build()*/;
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建Restful Api")
.version("1.0")
.build();
}

}

这次变化之后,好了,配置类的配置内容也出现了,接口说明文档也出现了,但是还有问题.

再次出现的问题

我按照现在好用的配置方式,原封不动的添加到我的项目中,结果swagger-ui.HTML页面无法访问了,在网上查,发现是因为我在application.properties文件中配置了spring.mvc.view.prefix和spring.mvc.view.suffix,然后访问swagger-ui.html就被影响到了,

解决方法

swagger的配置类继承WebMvcConfigurerAdapter,重写addResourceHandlers方法,具体的最终配置类如下:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@ComponentScan("xx.xx.xx")
public class SwaggerConfig extends WebMvcConfigurerAdapter {

/**
* 配置文件中配置了页面访问的相关信息,就需要有该方法,否则无法访问swagger-ui.html
* @param registry --
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}

@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建Restful Api")
.description("Spring boot Swagger2 study：Spring boot Swagger2 study")
.termsOfServiceUrl("Spring boot Swagger2 study")
.contact("qhong")
.version("1.0")
.build();
}

}

还有最后的一处变化,是在启动类中

无意中发现的,启动类中不需要@EnableSwagger2这个注解

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SwaggerApplication {

public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class);
}
}

最后贴出完整版的代码

POM文件

<!-- Spring Boot 启动父依赖 核心模块，包括自动配置支持、日志和YAML-->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.5.1.RELEASE</version>
</parent>

<dependencies>

<!-- Spring Boot web依赖 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!--SeaSwagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>

<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>

<!-- 实现spring boot的热部署 -->
<dependency>
<!--Spring 官方提供的热部署插件 -->
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<optional>true</optional>
</dependency>

</dependencies>

<build>

<finalName>SpringBoot_Study</finalName>

<plugins>

<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<dependencies>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>springloaded</artifactId>
<version>1.2.6.RELEASE</version>
</dependency>
</dependencies>
</plugin>

</plugins>

</build>

启动类

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class SwaggerApplication {

public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class);
}
}

Controller层

import cn.zfs.swagger.model.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

/**
* @Api：用在类上，说明该类的作用
* @ApiOperation：用在方法上，说明方法的作用
* @ApiImplicitParams：用在方法上包含一组参数说明
* @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
*              paramType：参数放在哪个地方
*                  header-->请求参数的获取：@RequestHeader
*                  query-->请求参数的获取：@RequestParam
*                  path（用于restful接口）-->请求参数的获取：@PathVariable
*                  body（不常用）
*                  form（不常用）
*              name：参数名
*              dataType：参数类型
*              required：参数是否必须传
*              value：参数的意思
*              defaultValue：参数的默认值
*              httpMethod:设置请求方式
* @ApiResponses：用于表示一组响应
* @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400
*              message：信息，例如"请求参数没填好"
*              response：抛出异常的类
* @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
* @ApiModelProperty：描述一个model的属性
*/
@RestController
@Api("http相关接口")
public class SwaggerDemoController {

ArrayList<User> userList = new ArrayList<>();

@ApiOperation(value = "获取用户列表", notes = "获取用户列表--notes", produces = "application/json")
@ApiResponses(value = {
@ApiResponse(code = 405, message = "405 错误"), // 在默认Response的基础上增加新的Response说明
@ApiResponse(code = 404, message = "404 错误") // 覆盖404错误的说明
})
@ApiImplicitParam(name = "username", value = "用户名称", dataType = "string", paramType = "query") //描述接口参数
@RequestMapping(value = "/getuserlist", method = RequestMethod.POST)
public List<User> getUserList(String username) {
userList.add(new User("张三"));
userList.add(new User("李四"));
userList.add(new User("王五"));
if (!userList.contains(new User(username))) {
userList.add(new User(username + "(我不在顺序当中)"));
}
return userList;
}

@ApiOperation(value = "添加用户", notes = "添加用户--notes")
@ApiImplicitParams(value = { // 描述多个参数
@ApiImplicitParam(name = "username", value = "用户名称", paramType = "query", dataType = "String")
})
@RequestMapping(value = "/adduser", method = RequestMethod.POST)
public String addUser(String username) {
userList.add(new User(username));
return "更新成功";
}

/**
* 这种方式不是很好
*
* @param id
* @return
*/
@ApiOperation(value = "根据id删除用户", notes = "根据id删除用户--notes", httpMethod = "POST")
@RequestMapping("/delUser")
public User delUser(@ApiParam(value = "用户ID", required = true) @RequestParam int id) {
User user = userList.remove(id);
return user;
}

/**
* 这种方式不行 kill
*
* @param id
* @return
*/
@ApiOperation(value = "根据id删除用户.bak", httpMethod = "POST")
@ApiParam(value = "用户id", required = true)
@RequestMapping("/deluserBak")
public User deluserBak(int id) {
User user = userList.remove(id);
return user;
}

@ApiOperation(value = "添加用户",httpMethod = "POST")
/*  @ApiImplicitParams(value = {
@ApiImplicitParam(name = "username",required = true,value = "用户名称",paramType = "query")
})*/
@RequestMapping("/saveUser")
public List<User> saveuser(@ModelAttribute User user){
userList.add(user);
return userList;
}
}

配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@ComponentScan("cn.zfs") // 注意这里的包
public class SwaggerConfig extends WebMvcConfigurerAdapter {

/**
* 如果你在配置文件中配置了页面访问的相关信息,就需要有该方法,否则无法访问swagger-ui.html
* @param registry --
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}

@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("cn.zfs"))// 注意这里的包
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建Restful Api") //设置文档的标题
.description("Spring boot Swagger2 study：Spring boot Swagger2 study") //设置文档的描述->1.Overview
.termsOfServiceUrl("Spring boot Swagger2 study") //设置文档的License信息->1.3 License information
.contact("qhong")//设置文档的联系方式->1.2 Contact information
.version("1.0")
.build();
}

}

swagger一些注解的简单解释

引用:http://www.cnblogs.com/java-zhao/p/5348113.html

/**
* @Api：用在类上，说明该类的作用
* @ApiOperation：用在方法上，说明方法的作用
* @ApiImplicitParams：用在方法上包含一组参数说明
* @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
*              paramType：参数放在哪个地方
*              header-->请求参数的获取：@RequestHeader
*              query-->请求参数的获取：@RequestParam
*              path（用于restful接口）-->请求参数的获取：@PathVariable
*              body（不常用）
*              form（不常用）
*              name：参数名
*              dataType：参数类型
*              required：参数是否必须传
*              value：参数的意思
*              defaultValue：参数的默认值
*              httpMethod:设置请求方式
* @ApiResponses：用于表示一组响应
* @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400
*              message：信息，例如"请求参数没填好"
*              response：抛出异常的类
* @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
* @ApiModelProperty：描述一个model的属性
*/

model对象

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "User",discriminator = "用户")
public class User {

public User() {
}

public User(String username) {
this.username = username;
}

@ApiModelProperty(name = "username",value = "姓名")
private String username;

public String getUsername() {
return username;
}

public void setUsername(String username) {
this.username = username;
}
}