尤其在当前前后端分离的大趋势下，编写和维护开发接口的文档是每个程序员必要的职责。Swagger 首先是一个规范、完整和统一的接口文档维护规范/标准。在这个标准下，Swagger官方提供了很多基于该标准的自动化接口维护工具，用于生成、描述、调用和可视化接口文档的Web 服务。该工具主要包括以下三个部分：
- Swagger Codegen：通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多种语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
- Swagger UI：提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
- Swagger Editor：类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
在SpringBoot中，由于Swagger的大流行，Spring 基于Swagger 的标准/规范，开发了一套适用于Spring生态的接口工具框架 Springfox-swagger ，可以将基于SpringMVC和Spring Boot项目的项目代码，按照Swagger规范自动生成JSON格式的描述文件并进行展示。Swagger发展到今天，已经有2.x和3.x两种主流的大版本，同样Springfox-swagger也有两种相应的版本，两种版本略有不同，我们这里主要讲Swagger3的整合与使用。
二.SpringBoot整合Swagger3环境搭建 1.引入maven依赖springfox-boot-starter 该starter包含了一些swagger必要的自动配置类和启动器，其主要包括：
- springfox-swagger：swagger核心，生成接口文档的Json格式数据
- springfox-swagger-ui：swagger可视化，将Json数据可视化展示
io.springfox
springfox-boot-starter
3.0.0
spring boot 2.6.x或更高版本集成Swagger时，直接运行会出现异常信息报错（空指针），主要原因是：Spring Boot 2.6及 更高版本使用的默认路径匹配规则是PathPatternMatcher，而Springfox使用的路径匹配是基于AntPathMatcher的。所以这里需要更改一下SpringBoot配置。
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
配置类中各部分配置的含义都已经通过注释说明了，这里主要介绍RequestHandlerSelectors和PathSelectors的接口扫描与展示过滤规则，其中：
- RequestHandlerSelectors：
- any()：扫描项目所有包下的所有接口
- none()：不扫描接口
- withMethodAnnotation：通过方法上的指定注解扫描接口
- withClassAnnotation：通过类上的指定注解扫描接口
- basePackage：根据包路径扫描接口
- PathSelectors：
- any() ：任何接口路径Url都扫描展示
- none()：任何接口路径Url都不扫描展示
- regex：通过正则表达式控制接口路径Url扫描展示
- ant：通过 ant 路径匹配控制接口路径Url扫描展示
@Configuration //声明配置类
@EnableOpenApi //开启swagger支持
public class SwaggerConfig {
/**
* Docket类是Swagger的配置类，要自定义修改Swagger的默认配置信息，我们需要覆盖该对象
* @return
*/
@Bean
public Docket docket(){
//1.以OAS_30标准构建Docket配置类
return new Docket(DocumentationType.OAS_30)
//2.配置Swagger接口文档基本信息apiInfo
.apiInfo(apiInfo())
//3.select方法开启配置扫描接口的Builder
.select()
//4.指定要扫描/维护接口文档的包（否则就全部扫描）
.apis(RequestHandlerSelectors.basePackage("com.example.bootswagger.controller"))
//5.路径过滤：该Docket-UI展示时，只展示指定路径下的接口文档(any表示都展示)
.paths(PathSelectors.any())
.build();
}
/**
* 配置 Swagger 接口文档的基本信息
* @return
*/
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
//1.接口文档标题
.title("SpringBoot整合Swagger")
//2.接口文档描述内容
.description("这里是SpringBoot整合Swagger的详细信息......，包括...")
//3.项目文档迭代版本
.version("9.0")
//4.主要联系人信息（姓名name，个人主页url，邮箱email）
.contact(new Contact("阿安","www.baidu.com","[email protected]"))
//5.相关许可证信息
.license("The CSDN License")
//6.相关许可证链接
.licenseUrl("www.baidu.com")
//7.返回构建的ApiInfo对象
.build();
}
}
4.Swagger分组配置配置完成后启动SpringBoot项目，访问 http://localhost:8080/swagger-ui/index.html 或 http://localhost:8080/swagger-ui/ 即可看到生成的接口文档。
在实际开发中，可能是是由很多人来共同开发一组接口功能，每个人负责不同的部分。那么对于每个人/每个小组负责的文档部分也应该进行分组，使得开发过程更加清晰。在Swagger实现中，一个Docket配置类对应一组文档配置，既然要进行分组，那么分几组我们就要分别配置几个相应的Docket对象，然后通过groupName()方法配置分组信息（名称）。
@Configuration //声明配置类
@EnableOpenApi //开启swagger支持
public class SwaggerConfig {
/**
* 配置分组文档 docketA ：该部分文档由王五负责，主要涉及UserController相应接口的开发，对应url为 /user/**
* @return
*/
@Bean
public Docket docketA(){
//1.以OAS_30文档标准构建Docket配置类
return new Docket(DocumentationType.OAS_30)
//2.配置Swagger接口文档基本信息apiInfoA
.apiInfo(apiInfoA())
//3.配置文档分组-名称
.groupName("docketA")
//4.select方法开启配置扫描接口的Builder
.select()
//5.指定要扫描/维护接口文档的包：bootswagger.controller
.apis(RequestHandlerSelectors.basePackage("com.example.bootswagger.controller"))
//6.指定路径过滤规则：docketA只展示 /user/** 路径下的接口描述（配合包扫描）
.paths(PathSelectors.ant("/user/**"))
.build();
}
/**
* 配置分组文档 docketB ：该部分文档由李四负责，主要涉及AdminController相应接口的开发，对应url为 /admin/**
* @return
*/
@Bean
public Docket docketB(){
//1.以OAS_30文档标准构建Docket配置类
return new Docket(DocumentationType.OAS_30)
//2.配置Swagger接口文档基本信息apiInfoB
.apiInfo(apiInfoB())
//3.配置文档分组-名称
.groupName("docketB")
//4.select方法开启配置扫描接口的Builder
.select()
//5.指定要扫描/维护接口文档的包：bootswagger.controller
.apis(RequestHandlerSelectors.basePackage("com.example.bootswagger.controller"))
//6.指定路径过滤规则：docketA只展示 /user/** 路径下的接口描述（配合包扫描）
.paths(PathSelectors.ant("/admin/**"))
.build();
}
/**
* 配置 文档A 的基本信息
* @return
*/
private ApiInfo apiInfoA(){
return new ApiInfoBuilder()
//1.接口文档标题
.title("文档A：SpringBoot整合Swagger")
//2.接口文档描述内容
.description("这里是SpringBoot整合Swagger的详细信息......，包括...")
//3.项目文档迭代版本
.version("9.0")
//4.主要联系人信息（姓名name，个人主页url，邮箱email）
.contact(new Contact("王五","www.baidu.com","[email protected]"))
//7.返回构建的ApiInfo对象
.build();
}
/**
* 配置 文档B 的基本信息
* @return
*/
private ApiInfo apiInfoB(){
return new ApiInfoBuilder()
//1.接口文档标题
.title("文档B：SpringBoot整合Swagger")
//2.接口文档描述内容
.description("这里是SpringBoot整合Swagger的详细信息......，包括...")
//3.项目文档迭代版本
.version("2.0")
//4.主要联系人信息（姓名name，个人主页url，邮箱email）
.contact(new Contact("李四","www.baidu.com","[email protected]"))
//7.返回构建的ApiInfo对象
.build();
}
}
欢迎分享，转载请注明来源：内存溢出
微信扫一扫
支付宝扫一扫
评论列表（0条）