全局逻辑梳理
温馨提示
在这里,你将系统学习了解全局逻辑梳理
的相关内容
# Knife4j 接口文档配置
推荐阅读:Knife4j 版本参考 | Knife4j (xiaominfo.com) (opens new window)
配置完成后,在本机访问该地址即可访问项目接口文档:Memory OJ 在线判题系统 接口文档 (opens new window)
这里在看过官方文档之后,清楚了 Spring Boot
和 Knife4j
的版本兼容性问题:
官方文档描述得很清楚,在 Spring Boot 2.x
版本下,如果使用的 Knife4j
版本 < 4.0.0
,则导入以下依赖坐标:
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
在该版本下,Knife4j
提供对Swagger2
规范的适配,底层规范解析框架依赖 springfox (opens new window)项目。在项目中作如下配置:
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
@Profile({"dev", "test"})
public class Knife4jConfig {
@Bean
public Docket defaultApi2() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfoBuilder()
.title("Memory OJ 在线判题系统 接口文档")
.description("Memory OJ 在线判题系统")
.version("1.0")
.build())
.select()
// 指定 Controller 扫描包路径
.apis(RequestHandlerSelectors.basePackage("com.memory.oj.controller"))
.paths(PathSelectors.any())
.build();
}
}
访问接口文档地址,效果如下,挺简陋的:
如果使用的 Knife4j
版本 > 4.0.0
,则导入以下依赖坐标:
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
<version>4.0.0</version>
</dependency>
可以看到,在该版本下,maven 组件的artifactId
已经发生了变化。Knife4j
提供对openapi2
规范的适配,底层规范解析框架依赖 springdoc-openapi (opens new window) 项目。在项目中作如下配置:
@Configuration
@Profile({"dev", "test"})
public class Knife4jConfig {
@Bean
public Docket defaultApi2() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfoBuilder()
.title("Memory OJ 在线判题系统 接口文档")
.description("Memory OJ 在线判题系统")
.contact("3348407547qq.com")
.version("1.0")
.build())
.select()
// 指定 Controller 扫描包路径
.apis(RequestHandlerSelectors.basePackage("com.memory.oj.controller"))
.paths(PathSelectors.any())
.build();
}
}
访问接口文档地址,效果如下:
也可以在application.yaml
文件下,做如下配置:
knife4j:
enable: true
openapi:
title: Memory OJ 在线判题系统 接口文档
description: Memory OJ 在线判题系统
concat: 3348407547@qq.com
url: https://deng-2022.gitee.io/blog/
version: 1.0
license: Apache 2.0
group:
test1:
group-name: memory-oj
访问接口文档地址,效果如下:
当然,以上分组配置group
可以省略,Knife4j
提供默认分组 URL,但文档简介和作者似乎失效了,效果如下:
总而言之,如果你使用的是 Spring Boot 2.x
版本,建议你导入基于openapi
规范的 knife4j
依赖坐标,并使用 application.yaml
配置文件来进行 Knife4j
接口文档配置
在 Spring Boot 3.x 版本下,导入以下依赖坐标:
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.2.0</version>
</dependency>
这是因为自 4.0 版本开始,Knife4j
提供对 OpenAPI3
规范的适配,底层规范解析框架依赖 springdoc-openapi (opens new window) 项目。
由于springfox
长久未更新,并且Swagger2
规范在目前来看,一定程度上也并未升级,规范已经全部往OpenAPI3
规范靠拢,因此,在Spring Boot 3.x
版本中,开发者应该选择OpenAPI3
规范来作为应用框架的开发首选方案。
项目的相关配置如下(这部分还未实践,接口文档的效果暂时不能展示,待我测试之后再来补充):(2024/01/27 晚)
# springdoc-openapi项目配置
springdoc:
swagger-ui:
path: /swagger-ui.html
tags-sorter: alpha
operations-sorter: alpha
api-docs:
path: /v3/api-docs
group-configs:
- group: "default"
paths-to-match: "/**"
packages-to-scan: com.xiaominfo.knife4j.demo.web
# knife4j的增强配置,不需要增强可以不配
knife4j:
enable: true
setting:
language: zh_cn