Spring Boot 集成 Swagger 在线接口文档

Spring Boot 集成 Swagger 在线接口文档

1. Swagger 简介

1.1 解决的问题随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了前后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系变成了 API 接口，所以 API 文档变成了前后端开发人员联系的纽带，变得越来越重要。
那么问题来了，随着代码的不断更新，开发人员在开发新的接口或者更新旧的接口后，由于开发任务的繁重，往往文档很难持续跟着更新，Swagger 就是用来解决该问题的一款重要的工具，对使用接口的人来说，开发人员不需要给他们提供文档，只要告诉一个 Swagger 地址，即可展示在线的 API 接口文档，除此之外，调用接口的人员还可以在线测试接口数据，同样地，开发人员在开发接口时，同样也可以利用 Swagger 在线接口文档测试接口数据，这给开发人员提供了便利。
1.2 Swagger 官方
打开 Swagger 官网为 https://swagger.io/ 掌握在 Spring Boot 中如何导入 Swagger 工具来展现项目中的接口文档。

2.依赖导入

Swagger 的 maven 依赖使用 Swagger 工具，必须要导入 maven 依赖

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
</dependency>

3. Swagger 配置

使用 Swagger 需要进行配置，Spring Boot 中对 Swagger 的配置非常方便，新建一个配置类，Swagger 的配置类上除了添加必要的@Configuration 注解外，还需要添加@EnableOpenApi 注解。

package com.lanou.conf;

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

@EnableOpenApi
@Configuration
public class Swagger3Config {

    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * swagger测试地址：http://localhost:8080/swagger-ui/index.html#/
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30) // 使用Swagger3.0版本
                .enable(true)// 是否关闭在线文档，生产环境关闭
                .apiInfo(apiInfo())  // 指定构建api文档的详细信息的方法
                .select()  // 指定要生成api接口的包路径，这里把action作为包路径，生成controller中的所有接口
                .apis(RequestHandlerSelectors.basePackage("com.lanou.action"))
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))方法接口上添加了ApiOperation注解
                .paths(PathSelectors.any()).build()
                //针对应用的全局响应消息配置
//                .globalResponses(HttpMethod.GET, getGlobalResponseMessage())
//                .globalResponses(HttpMethod.POST, getGlobalResponseMessage())
                ;
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档") //设置页面标题
                .description("说明信息")  //设置接口描述
                .contact(new Contact("song", "http://baidu.com", "yan@yan.com")) //设置联系方式
                .version("1.0") //设置版本
                .build();  //构建
    }
}

在该配置类中已经使用注释详细解释了每个方法的作用了。
到此已经配置好 Swagger 了。现在可以测试一下配置有没有生效，启动项目，在浏览器中输入 http://localhost:8080/test/swagger-ui/，即可看到 swagger 的接口页面，说明 Swagger 集成成功。

对照 Swagger 配置文件中的配置，可以很明确的知道配置类中每个方法的作用。

由于Bug因此要在spring配置文件里面加入相关配置

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

4. Swagger 的使用

已经配置好了 Swagger，并且也启动测试了一下，功能正常，下面可以开始使用 Swagger，重点要掌握 Swagger 中常用的注解，分别在实体类上、Controller 类上以及 Controller 中的方法上，最后查看 Swagger 如何在页面上呈现在线接口文档的，并且结合 Controller 中的方法在接口中测试一下数据。
4.1 实体类注解
定义 User 实体类，这里主要介绍 Swagger 中的@ApiModel 和@ApiModelProperty 注解。

@ApiModel(value = "用户实体类") 
public class User { 
	@ApiModelProperty(value = "用户唯一标识") 
	private Long id;
	@ApiModelProperty(value = "用户姓名") 
	private String username;
	@ApiModelProperty(value = "用户密码") 
	private String password;
	// 省略 set 和 get 方法
}

其中
@ApiModel 注解用于实体类，表示对类进行说明，用于参数用实体类接收。
@ApiModelProperty 注解用于类中属性，表示对 model 属性的说明或者数据操作更改。
4.2 Controller 类中相关注解

@RestController
@RequestMapping("/swagger")
@Api(value = "Swagger2 在线接口文档")
public class TestController {
	@GetMapping("/get/{id}")
	@ApiOperation(value = "根据用户唯一标识获取用户信息")
	public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用户唯一标识") Long id) {
		// 模拟数据库中根据 id 获取 User 信息
		User user = new User(id, "闫峻", "123456");
		return new JsonResult(user);
	}
}

1、 @Api 注解用于类上，表示标识这个类是 swagger 的资源。
2、 @ApiOperation 注解用于方法，表示一个 http 请求的操作。
3、 @ApiParam 注解用于参数上，用来标明参数信息。
在浏览器中可以看出 Swagger 页面对该接口的信息展示的非常全面，每个注解的作用以及展示的地方注意对应位置，通过页面即可知道该接口的所有信息，那么直接在线测试一下该接口返回的信息，输入 id 为 1，看一下返回数据。
可以看出，直接在页面返回了 json 格式的数据，开发人员可以直接使用该在线接口来测试数据的正确与否，非常方便。

@PostMapping("/insert")
@ApiOperation(value = "添加用户信息")
public JsonResult<Void> insertUser(@RequestBody @ApiParam(value = "用户信息") User user) {
	// 处理添加逻辑
	return new JsonResult<>(); 
} 

重启项目，然后在浏览器中输入 localhost:8080/swagger-ui.html 看效果

5. 总结

主要详细分析 Swagger 的优点以及 Spring Boot 集成 Swagger，包括配置，涉及到了实体类和接口类以及如何使用。最后通过页面测试，可以体验 Swagger 的强大之处，基本上是每个项目组中必备的工具之一，所以要掌握该工具的使用。