技术分享 | Spring Boot 集成 Swagger
Swagger UI 允许任何人（无论您是开发团队还是最终用户）都可以可视化 API 资源并与之交互，而无需任何实现逻辑。它是根据您的 OpenAPI（以前称为 Swagger）规范自动生成的，具有可视化文档，可简化后端实现和客户端使用。
为什么使用Swagger
跨语言性，支持 40 多种语言，Swagger 已经慢慢演变成了 OpenAPI 规范；
Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程；
对于某些没有前端界面 UI 的功能，可以用它来测试接口；
联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位问题。
Swagger快速开始
这里选择 2.9.2 版本。
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
添加配置类
添加一个 Swagger 配置类，在工程下新建 config 包并添加一个 SwaggerConfig 配置类。
SwaggerConfig.java
```java
import com.google.common.collect.Lists;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
//作为Springfox框架的主要接口的构建器,提供合理的默认值和方便的配置方法。
@Bean
public Docket docket() {
ParameterBuilder builder = new ParameterBuilder();
builder.parameterType("header").name("token")
.description("token值")
.required(true)
.modelRef(new ModelRef("string")); // 在swagger里显示header
return new Docket(DocumentationType.SWAGGER_2)
.groupName("aitest_interface")
.apiInfo(apiInfo())
.globalOperationParameters(Lists.newArrayList(builder.build()))
.select().paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("aitest-mini系统")
.description("aitest-mini接口文档")
.contact(new Contact("tlibn", "", "103@qq.com"))
.version("1.0")
.build();
}
}
添加控制器
添加一个控制器，在工程下新建 controller包并添加一个Controller控制器，如果已经存在Controller控制器，则直接启动服务也可以，如上章我们编写了HogwartsTestUserController类，此时直接启动服务即可。
打开 swagger 接口文档界面
启动 Spring Boot 服务，打开浏览器，访问：http://127.0.0.1:8081/swagger-ui.html，进入swagger接口文档界面。 6
测试
展开 hogwarts-test-user-controller 的任意接口，输入参数并点击执行，就可以看到接口测试结果了。
Swagger 常用注解
swagger 通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。
Api：修饰整个类，描述 Controller 的作用
Api(tags = “霍格沃兹测试学院-用户管理模块”, hidden = true)
ApiOperation：描述一个类的一个方法，或者说一个接口
ApiOperation(“查询用户列表”)
ApiParam：单个参数描述
ApiModel：用对象来接收参数
ApiModel(value = “用户登录类”, description = “请求类”)
ApiProperty：用对象接收参数时，描述对象的一个字段
ApiModelProperty(value=“用户id”, example=“1”,required=true)
ApiResponse：HTTP 响应其中 1 个描述
ApiResponses：HTTP 响应整体描述
ApiIgnore：使用该注解忽略这个 API
ApiError ：发生错误返回的信息
ApiImplicitParam：一个请求参数
ApiImplicitParams：多个请求参数
更多参见 https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#quick-annotation-overview
添加 Swagger 常用注解后的效果
添加 Swagger 常用注解后的示例代码
HogwartsTestUserController.java
@Api(tags = “霍格沃兹测试学院-用户管理模块”, hidden = true)
@RestController
@RequestMapping("/api/user")
public class HogwartsTestUserController {
/**
* 查询用户列表，返回一个JSON数组
* */
@ApiOperation("查询用户列表")
@GetMapping("/users")
@ResponseStatus(HttpStatus.OK)
public Object getUsers(){
List<UserDto> list = getData();
return list;
}
/**
* 查询用户信息，返回一个新建的JSON对象
* */
@ApiOperation("查询用户信息")
@GetMapping("/users/{id}")
@ResponseStatus(HttpStatus.OK)
public Object getUser(@PathVariable("id") Long id){
if(Objects.isNull(id)){
return null;
}
List<UserDto> list= getData();
UserDto userDto = getUserDto(id, list);
return userDto;
}
/**
* 新增用户
* */
@ApiOperation("新增用户")
@PostMapping("/users")
@ResponseStatus(HttpStatus.CREATED)
public Object addUser(@RequestBody UserDto user){
List<UserDto> list= getData();
list.add(user);//模拟向列表中增加数据
return user;
}
/**
* 编辑用户
* */
@ApiOperation("编辑用户")
@PutMapping("/users/{id}")
@ResponseStatus(HttpStatus.CREATED)
public Object editUser(@PathVariable("id") Long id,@RequestBody UserDto user){
List<UserDto> list = getData();
for (UserDto userDto:list) {
if(id.equals(userDto.getId())){
userDto = user;
break;
}
}
return user;
}
/**
* 删除用户
* */
@ApiOperation("删除用户")
@DeleteMapping("/users/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public Object deleteUser(@PathVariable("id") Long id){
List<UserDto> list = getData();
UserDto userDto = getUserDto(id, list);
return userDto;
}
/**
* 模拟数据
* */
private List<UserDto> getData(){
List<UserDto> list=new ArrayList<>();
UserDto userDto = new UserDto();
userDto.setId(1L);
userDto.setName("admin");
userDto.setPwd("admin");
list.add(userDto);
userDto = new UserDto();
userDto.setId(2L);
userDto.setName("HogwartsTest1");
userDto.setPwd("HogwartsTest1");
list.add(userDto);
userDto = new UserDto();
userDto.setId(3L);
userDto.setName("HogwartsTest2");
userDto.setPwd("HogwartsTest2");
list.add(userDto);
userDto = new UserDto();
userDto.setId(4L);
userDto.setName("HogwartsTest3");
userDto.setPwd("HogwartsTest3");
list.add(userDto);
return list;
}
/**
* 模拟根据id查询列表中的数据
* @param id
* @param list
* @return
*/
private UserDto getUserDto( Long id, List<UserDto> list) {
UserDto UserDto = null;
for (UserDto user : list) {
if (id.equals(user.getId())) {
UserDto = user;
break;
}
}
return UserDto;
}
}
UserDto.java
@ApiModel(value = “用户登录类”, description = “请求类”)
public class UserDto {
@ApiModelProperty(value="用户id", example="1",required=true)
private Long id;
@ApiModelProperty(value="用户名称", example="hogwarts1",required=true)
private String name;
@ApiModelProperty(value="用户密码", example="hogwarts2",required=true)
private String pwd;
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getPwd() {
return pwd;
}
public void setPwd(String pwd) {
this.pwd = pwd;
}
}
