Spring Boot 集成 Swagger2实战教程

简介

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

添加依赖

Maven依赖示例：

<!-- Swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
</dependency>

在 Spring Boot 配置文件中添加配置参数。

swagger:
title: API标题
description: API描述
version: 1.0
terms-of-service-url: http://www.javastack.cn/
base-package: cn.javastack.test.web
contact:
name: Javastack
url: http://www.javastack.cn/
email: admin@javastack.cn

添加配置类

@Getter
@Setter
@Configuration
@EnableSwagger2
@ConditionalOnClass(EnableSwagger2.class)
@ConfigurationProperties(prefix = "swagger")
public class SwaggerConfig {
/**
* API接口包路径
*/
private String basePackage;
/**
* API页面标题
*/
 private String title;
/**
* API描述
*/
private String description;
/**
* 服务条款地址
*/
private String termsOfServiceUrl;
/**
* 版本号
*/
private String version;
/**
* 联系人
*/
private Contact contact;
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(basePackage))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(title)
.description(description)
.termsOfServiceUrl(termsOfServiceUrl)
.version(version)
.contact(contact)
.build();
}
}

如何使用

Swagger 默认会根据配置的包，扫描所有接口并生成对应的 API 描述和参数信息，但这样不
是很直观，需要对每个接口和参数进行自定义描述。
常用的 Swagger 注解如下。

@Api
描述一个 API 类
@ApiImplicitParam
描述一个请求参数
@ApiImplicitParams
描述一组请求参数
@ApiModel
描述一个返回的对象
@ApiModelProperty
描述一个返回的对象参数
@ApiOperation
描述一个 API 方法
@ApiParam
描述一个方法的参数
@ApiResponse
描述一个请求响应
@ApiResponses
描述一组请求响应
使用示例如：
http://localhost:8080/swagger-ui.html
打开 swagger-ui 界面，可以看到所有的 API 接口定义，也可以在上面发起接口测试。

新建接口类

新建一个接口类，如下：
/**
*

• 用户管理

*/
@Api(value = “user”, description = “用户管理”, produces = MediaType.APPLICATION_JSON_VALUE)
@Controller
@RequestMapping(“user”)
public class UserController {

// 列出某个类目的所有规格
@ApiOperation(value = "获得用户列表", notes = "列表信息", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_VALUE)
@ResponseBody
@RequestMapping(value = "list", method = RequestMethod.GET)
public Result<User> list(
		@ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,	
		@ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId2,
		@ApiParam(value = "token", required = true) @RequestParam String token) {
	Result<User> result = new Result<User>();
	User user = new User();
	user.setName("zhangsan");
	user.setPassword("password");
	user.setSex(1);
	user.setToken("aastewetwewe97wewesf7w8");
	result.setData(user);
	return result;
}

@RequestMapping(value = "getUserById", method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value = "根据id获得用户信息", notes = "用户信息", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_VALUE)
public User getUserById(
		@ApiParam(value = "user ID", required = true) @RequestParam String id
		){
	User user = new User();
	user.setName("lisi");
	user.setPassword("password");
	user.setSex(1);
	user.setToken("aastewetwewe97wewesf7w8");
	return user;
}

@ApiOperation(value = "添加用户", notes = "添加用户(用于数据同步)", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
@ResponseBody
@RequestMapping(value = "add", method = RequestMethod.POST)
// @RequestBody只能有1个
// 使用了@RequestBody，不能在拦截器中，获得流中的数据，再json转换，拦截器中，也不清楚数据的类型，无法转换成java对象
// 只能手动调用方法
public Result<String> add(@RequestBody User user) {
	String u = findUser(user);
	System.out.println(u);
	return null;
}

@ApiOperation(value = "update用户", notes = "update user", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
@ResponseBody
@RequestMapping(value = "update", method = RequestMethod.GET)
public Result<String> update(User user) {
	String u = findUser(user);
	System.out.println(u);
	return null;	
}

private String findUser(User user) {
	String token = user.getToken();
	return token;
}

}

类注释解释

@API，用来描述Controller类的注释，value表示Controller的链接地址，访问此类的URL中需要加上/user，description表示描述，produces表示返回数据结构

方法注释解释

@APIOperation，用来描述方法的注释，value表示访问此方法的链接地址，如在user类下的list方法，如/user/list访问即可，notes表示方法的描述，httpMethod表示请求方式，produces表示返回数据结构
@ApiParam，用来描述参数的注释，value表示参数名，required表示是否必填。
@RequestParam，用来表示参数类型。

实体类注释解释

@ApiModel，表示实体类注释，value表示对象名称，description表示描述
@ApiModeProperty，表示描述字段的注释，value表示字段名,required表示是否必填。