一、引用Knife4j的starter,Maven坐标
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.4.0</version>
</dependency>
二、配置yml
目前给出的是扫描一个大包,后面会有分组的代码
# springdoc-openapi项目配置
springdoc:
swagger-ui:
path: /swagger-ui.html
tags-sorter: alpha
operations-sorter: alpha
api-docs:
path: /v3/api-docs
group-configs:
- group: 'all'
paths-to-match: '/**'
packages-to-scan: com.quick.controller
# knife4j的增强配置,不需要增强可以不配
knife4j:
enable: true
setting:
language: zh_cn
参考官方中文文档:快速开始 | Knife4j
三、定义配置文件config
定义一个配置类WebMvcConfiguration,实现静态资源映射,保证生成的接口文档能够正常进行展示
/**
* 配置类,注册web层相关组件
*/
@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {
/**
* 设置静态资源映射
* @param registry
*/
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
log.info("开始设置静态资源映射...");
registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
两种分组方法:
1、建一个配置类SwaggerConfig,实现接口文档能够分组展示
@Configuration
public class SwaggerConfig {
@Bean
public GroupedOpenApi adminApi() {
return GroupedOpenApi.builder()
.group("管理端接口")
.pathsToMatch("/admin/**") // 根据你的实际路径进行配置
.build();
}
@Bean
public GroupedOpenApi userApi() {
return GroupedOpenApi.builder()
.group("C端接口")
.pathsToMatch("/user/**") // 根据你的实际路径进行配置
.build();
}
@Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("接口文档")
//描叙
.description("接口文档")
//版本
.version("v1")
//作者信息,自行设置
.contact(new Contact().name("bluefoxyu"))
//设置接口文档的许可证信息
.license(new License().name("Apache 2.0").url("http://springdoc.org")));
}
}
效果图如下
2、在上面的yml的配置类里面也设置了,我设置了扫描的包是user和admin的父包controller,里面的接口是所有子包接口的集合,效果图如下
group-configs:
- group: 'all'
paths-to-match: '/**'
packages-to-scan: com.quick.controller
当然也可以直接在yml配置文件里面配置分组信息,那样就不用在配置类里面定义以下代码,具体参考中文官方文档 :3.1 增强模式 | Knife4j
@Bean
public GroupedOpenApi adminApi() {
return GroupedOpenApi.builder()
.group("管理端接口")
.pathsToMatch("/admin/**") // 根据你的实际路径进行配置
.build();
}
@Bean
public GroupedOpenApi userApi() {
return GroupedOpenApi.builder()
.group("C端接口")
.pathsToMatch("/user/**") // 根据你的实际路径进行配置
.build();
}
以下给出修改的yml和完整的yml
- group: 'admin'
paths-to-match: '/**'
packages-to-scan: com.quick.controller.admin
- group: 'user'
paths-to-match: '/**'
packages-to-scan: com.quick.controller.user
# springdoc-openapi项目配置
springdoc:
swagger-ui:
path: /swagger-ui.html
tags-sorter: alpha
operations-sorter: alpha
api-docs:
path: /v3/api-docs
group-configs:
- group: 'admin'
paths-to-match: '/**'
packages-to-scan: com.quick.controller.admin
- group: 'user'
paths-to-match: '/**'
packages-to-scan: com.quick.controller.user
# knife4j的增强配置,不需要增强可以不配
knife4j:
enable: true
setting:
language: zh_cn
效果图如下:
综上所述:两种分组方法任选一种。
上面配置类里面的以下代码则是介绍,也可以在yml里面配置,以下就不再多说。
具体可以参考3.1 增强模式 | Knife4j
@Bean public OpenAPI springShopOpenAPI() { return new OpenAPI() .info(new Info() .title("餐途快取项目接口文档") //描叙 .description("餐途快取项目接口文档") //版本 .version("v1") //作者信息,自行设置 .contact(new Contact().name("bluefoxyu")) //设置接口文档的许可证信息 .license(new License().name("Apache 2.0").url("http://springdoc.org"))); }
4、实现接口文档的生成
网址:http://localhost:8080/doc.html
5、Swagger3 注解使用(Open API 3)
可参考官方文档里面入门快速案例:快速开始 | Knife4j
@RestController
@RequestMapping("body")
@Tag(name = "body参数")
public class BodyController {
@Operation(summary = "普通body请求")
@PostMapping("/body")
public ResponseEntity<FileResp> body(@RequestBody FileResp fileResp){
return ResponseEntity.ok(fileResp);
}
@Operation(summary = "普通body请求+Param+Header+Path")
@Parameters({
@Parameter(name = "id",description = "文件id",in = ParameterIn.PATH),
@Parameter(name = "token",description = "请求token",required = true,in = ParameterIn.HEADER),
@Parameter(name = "name",description = "文件名称",required = true,in=ParameterIn.QUERY)
})
@PostMapping("/bodyParamHeaderPath/{id}")
public ResponseEntity<FileResp> bodyParamHeaderPath(@PathVariable("id") String id,@RequestHeader("token") String token, @RequestParam("name")String name,@RequestBody FileResp fileResp){
fileResp.setName(fileResp.getName()+",receiveName:"+name+",token:"+token+",pathID:"+id);
return ResponseEntity.ok(fileResp);
}
}
swagger2和swagger3注解有些变化,具体可以参考:Swagger 2.X Annotations · swagger-api/swagger-core Wiki · GitHub
注意:swagger 3 注解的包路径为io.swagger.v3.oas.annotations.
这里参考了这位博主的博文:Swagger3 注解使用(Open API 3)_swagger3注解-CSDN博客
下面是我的一些代码改动
//controller
//@Api(tags = "通用接口")
@Tag(name = "通用接口")
//@ApiOperation("文件上传")
@Operation(summary = "文件上传")
//实体类
@Data
//@ApiModel(description = "员工登录时传递的数据模型")
@Schema(description = "员工登录时传递的数据模型")
public class EmployeeLoginDTO implements Serializable {
//@ApiModelProperty("用户名")
@Schema(description = "用户名")
private String username;
//@ApiModelProperty("密码")
@Schema(description = "密码")
private String password;
}
6、关于Knife4j文档请求异常问题
有可能是springboot版本和Knife4j的版本不一致问题,参考:Knife4j版本参考 | Knife4j
Spring Boot版本 | Knife4j Swagger2规范 | Knife4j OpenAPI3规范 |
---|---|---|
1.5.x~2.0.0 | <Knife4j 2.0.0 | >=Knife4j 4.0.0 |
2.0~2.2 | Knife4j 2.0.0 ~ 2.0.6 | >=Knife4j 4.0.0 |
2.2.x~2.4.0 | Knife4j 2.0.6 ~ 2.0.9 | >=Knife4j 4.0.0 |
2.4.0~2.7.x | >=Knife4j 4.0.0 | >=Knife4j 4.0.0 |
>= 3.0 | >=Knife4j 4.0.0 | >=Knife4j 4.0.0 |
还有一种情况我遇到过,这个博主的文章完美解决Knife4j文档请求异常(基于SpringBoot3,查找原因并解决)_standard commons logging discovery in action with -CSDN博客