提示:文章写完后,目录可以自动生成,如何生成可参考右边的帮助文档
前言
在当今流行的前后端分离项目中,接口文档扮演着不可或缺的角色,它建立了后端与前端之间的默契。在开始前端和后端开发之前,后端开发团队首先需要提供接口文档,而前端则依据这份文档来同步进行项目的开发。等双方的开发工作同步完成后就可以进入联调测试阶段,从而节省项目整体所需的时间。
接口文档通常分为两种类型:离线文档和实时文档。离线文档工具有一些局限性,比如Word文档(几乎不可维护)、YAPI和小幺鸡等。这些文档需要开发人员手动编写,并通常附带接口测试功能。一般情况下,开发人员会在离线接口文档中首先记录接口信息,然后将其交给前端开发人员参考,但最大的问题是当接口发生变更时,需要回头去维护文档内容,这非常繁琐。
而实时接口文档能够根据我们的代码自动生成相应的接口文档。如果我们的代码发生变化,生成的接口文档也会自动更新,无需手动维护,只需按时发布即可,非常方便。
而在实时接口文档的生成方案中,Swagger是最具影响力的一个。我们看下在Springboot项目中如何集成Swagger2和3,来实现接口文档的自动生成和更新。
一、SpringBoot集成Swagger2
下面先说下SpringBoot如何集成Swagger2。
1. pom文件引入依赖
<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>
2. 添加配置类
还需要添加配置类来配置 Swagger。配置类的代码如下:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口文档")
.description("接口文档")
.version("1.0.0")
.build();
}
}
3 在Controller类和对应方法以及入参、出参对象上使用注释(可选)
@Api:用在请求的类上,表示对类的说明
tags: 说明该类的作用,可以在UI界面上看到的注解
value: 该参数没什么意义,在UI界面上也看到,所以不需要配置
@ApiOperation:用在请求的方法上,说明方法的用途、作用
value: 说明方法的用途、作用
notes: 方法的备注说明
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
@ApiResponses:用在请求的方法上,表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiModel:用于响应类上,表示一个返回响应数据的信息,一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:用在属性上,描述响应类的属性
name:属性名
value:属性的汉字说明、解释
@ApiParam 用于 Controller 中方法的参数说明,放在方法签名当中
value:参数说明
required:是否必填
@ApiIgnore:使用该注解忽略这个API
查询入参类的使用示例:
public class TbDeptQuery extends PageQuery{
/** * 编号 */
@ApiParam(value = "编号", example = "100")
private Integer dno;
/** * 名称 */
@ApiParam(value = "名称")
private String dname;
/** * 所在地 */
@ApiParam(value = "所在地")
private String dloc;
// 省略get、set方法
}
响应出参类的使用示例:
public class PageVO<T> {
@ApiModelProperty(notes = "返回数据")
private List<T> content; // 当前页的数据
@ApiModelProperty(notes = "当前页数")
private int page; // 当前页数
@ApiModelProperty(notes = "每页大小")
private int size; // 每页大小
@ApiModelProperty(notes = "总数据条数")
private int totalElements; // 总数据条数
private int totalPages; // 总页数
public PageVO() {
// 默认构造函数
}
public PageVO(List<T> content, int page, int size, int totalElements) {
this.content = content;
this.page = page;
this.size = size;
this.totalElements = totalElements;
this.totalPages = (int) Math.ceil((double) totalElements / size); // 计算总页数 }
// 省略Getter和Setter方法
}
Controller类使用示例:
@Api(tags = "部门",value = "部门")
@RestController@RequestMapping(value = "/tbDept")
public class TbDeptController {
@Resourceprivate
TbDeptService tbDeptService;
/**
* 查询 分页查询
* @author taoxi
* @date 2023/09/29
**/
@ApiOperation("分页查询")
@RequestMapping("/pageList")
public PageVO<TbDept> pageList(TbDeptQuery query) {
return tbDeptService.pageList(query);
}
}
使用这个地址访问即可: http://localhost:8080/swagger-ui.html
4. 可能遇到的问题
如果使用SpringBoot 2.6.X以上版本,可能会报空指针异常,SpringBoot2.5.x及之前版本是没有问题的。
原因是因为Spring Boot 2.6.X使用PathPatternMatcher匹配路径,Swagger引用的Springfox使用的路径匹配是基于AntPathMatcher的。所以需要在springBoot属性文件中添加配置:
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
5. 更好的替换UI
上面的整个过程已经完成了,但是生成的接口文档的页面不太符合国人的使用习惯,所有又有一些大神,提供了其他的UI测试页面。这个页面的使用还是比较广泛的。
只需再引入一个依赖包:
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
访问路径也变为:http://localhost:8080/doc.html
二、SpringBoot集成Swagger3
1.引入依赖
这里引入增强包knife4j。
<!-- Swagger3 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
2. 在springBoot属性文件中添加配置
添加配置如下:
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
3. 添加配置类
swagger配置类如下:
@Configuration
@EnableKnife4j
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.enable(true)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("部门接口文档")
.description("swagger接口文档")
.version("1.0")
.build();
}
}
BeanPostProcessorConfig配置类:
@Configuration
public class BeanPostProcessorConfig {
@Bean
public BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {
return new BeanPostProcessor() {
@Override
public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
if (bean instanceof WebMvcRequestHandlerProvider || bean instanceof WebFluxRequestHandlerProvider) {
customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
}
return bean;
}
private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings(List<T> mappings) {
List<T> copy = mappings.stream()
.filter(mapping -> mapping.getPatternParser() == null)
.collect(Collectors.toList());
mappings.clear();
mappings.addAll(copy);
}
@SuppressWarnings("unchecked")
private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) {
try {
Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings");
field.setAccessible(true);
return (List<RequestMappingInfoHandlerMapping>) field.get(bean);
} catch (IllegalArgumentException | IllegalAccessException e) {
throw new IllegalStateException(e);
}
}
}
}
}
4. 在Controller类和对应方法以及入参、出参对象上使用注释(可选)
使用方法同Swagger2。
访问swagger-ui页面:http://localhost:8080/swagger-ui/index.html
访问knife4j-ui页面:http://localhost:8080/doc.html
总结
以上就是在Springboot项目中如何集成Swagger2和3,实现接口文档的自动生成和更新的方法。