技术分享 | 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

```javaimport 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@EnableSwagger2public 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;

}

}