Knife4j

Knife4j 使用教程

简介

Knife4j 是基于 springboot 构建的一个文档生成工具，它可以让开发者为我们的应用生成 API 文档，目的是可以更加方便的基于 API 文档进行测试，生成的文档还可以导出，然后给到前端开发团队，前端开发团队可以基于 API 接口写具体的调用。

版本参考

knife4j 目前主要支持以 Java 开发为主，并且支持 Spring MVC、Spring Boot、Spring Cloud 框架的集成使用。

Knife4j 的版本说明：

版本	说明
1.9.6	蓝色皮肤风格，开始更名，增加更多后端模块
2.0~2.0.5	Ui 重写，底层依赖的 springfox 框架版本是 2.9.2
2.0.6~2.0.9	底层 springfox 框架版本升级知 2.10.5，OpenAPI 规范是 v 2
3.0~3.0.3	底层依赖 springfox 框架版本升级至 3.0.3， OpenAPI 规范是 v 3
4.0~	4.0 重要版本，提供 OpenAPI 2 和 OpenAPI 3 两种规范供开发者自行选择，主版本统一

Knife4j 的引入要和 Spring Boot 的版本相匹配，所以得首先保证你项目中所使用的 Spring Boot 版本和 Knife4j 的兼容性，以下是版本兼容推荐：

Spring Boot 版本	knife4j Swagger 2 规范	knife4j OpenAPI 3 规范
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 提供的服务端增强功能，引入 Knife4j 的 纯UI版本 没有任何限制，只需要考虑不同的规范即可。

规范说明：

针对 Swagger 2 规范和 OpenAPI 3 规范的说明：

在 Spring Boot 框架中，knife4j 对于服务端将 Spring 开放接口解析成 Swagger 2 或者 OpenAPI 3 规范的框架，也是依赖的第三方框架组件。说明如下：
Swagger 2 规范：依赖 Springfox 项目，该项目目前几乎处于停更状态，但很多老项目依然使用的是该规范，所以 knife4j 在更新前端 UI 的同时也继续保持了兼容性
OpenAPI 3 规范：依赖 Springdoc 项目，更新发版频率非常快，建议开发者尽快迁移过来使用 OpenAPI 3 规范，knife4j 后面的重心也会在这里

基本使用

1. 导入相关依赖

Knife4j 的依赖需要兼容 Spring Boot 的版本，除此之外，有些低版本的 Knife4j 还需要保留 swagger 的相关依赖，并且 Knife4j 的版本要和 springfox 的版本相兼容，但是有些高版本的 Knife4j 是不需要引入 swagger 相关依赖的，例如 3.0.3 版本。

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

注意： 不能与 Swagger2 依赖一起使用，否则会报错

4版本之后包名发生变化

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

2. 开启 knife4j 配置

@SpringBootApplication
@EnableKnife4j // 在新版的 Knife4j 中，一般情况下不再需要手动添加 @EnableKnife4j 注解。
public class RedisDemo {
    public static void main(String[] args) {
        SpringApplication.run(RedisDemo.class,args);
    }
}

3. 编写 knife4j 配置

方式一：通过编写配置类

//4.0之后的版本不适用
@Bean
public Docket docket1() {
    ApiInfo apiInfo = new ApiInfoBuilder()
            .title("苍穹外卖项目接口文档")
            .version("2.0")
            .description("苍穹外卖项目接口文档")
            .build();
    Docket docket = new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.sky.controller.admin"))
            .paths(PathSelectors.any())
            .build().groupName("服务端接口");
    return docket;
}

@Bean
public Docket docket2() {
    ApiInfo apiInfo = new ApiInfoBuilder()
            .title("苍穹外卖项目接口文档")
            .version("2.0")
            .description("苍穹外卖项目接口文档")
            .build();
    Docket docket = new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.sky.controller.user"))
            .paths(PathSelectors.any())
            .build().groupName("客户端接口");
    return docket;
}

// 4.0之后的版本的写法
@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
            .group("接口分组名称")
            .pathsToMatch("/user/**") // 根据你的实际路径进行配置
            .build();
}

注意：. apis (RequestHandlerSelectors.basePackage (“com. sky. controller. user”)) == 自行修改

方式二：通过编写 yaml 文件（仅支持 4.1.0 之后）

knife4j:
  enable: true
  openapi:
    title: 黑马商城接口文档
    description: "黑马商城接口文档"
    email: zhanghuyi@itcast.cn
    concat: 虎哥
    url: https://www.itcast.cn
    version: v1.0.0
    group:
      default:
        group-name: default
        api-rule: package
        api-rule-resources:
          - com.hmall.controller # 指定自己的controller包

4. 开启静态资源映射

// WebMvcConfiguration
@Override
public void addResourceHandlers (ResourceHandlerRegistry registry) {
    //支持 webjars
    registry.addResourceHandler ("/webjars/**")
            .addResourceLocations ("classpath:/META-INF/resources/webjars/");
    //支持 swagger
    registry.addResourceHandler ("swagger-ui.html")
            .addResourceLocations ("classpath:/META-INF/resources/");
    //支持小刀
    registry.addResourceHandler ("doc.html")
            .addResourceLocations ("classpath:/META-INF/resources/");
}

5. 常用注解使用

@API：用于请求的类上，表示对类的说明。
- tags：说明该类的作用，可以在前台界面上看到的注解
- value：该参数无意义，在 UI 界面上看不到，不需要配置

用法：

@Api(tags = "【测试-方法】")
public class TestController {
	...
}

名称由 test-controller 改为 测试-方法。

@ApiOperation：该注解用来对某个方法/接口进行描述
- value：对该操作进行简单的描述
- notes：对操作的详细描述
- httpMethod：指定操作使用的 HTTP 方法类型，比如：“GET”、“POST”……但可以直接通过@GetMapping 等来指定，所以使用不多
- response：指定操作的响应类型，手动设置此属性将覆盖任何自动生成的数据类型。

用法：

@GetMapping("/get/{id}")
@ApiOperation(value = "get-测试方法")
public Result<TestDto> testGet(@PathVariable("id") Long id) {
	...
}

@ApiModel：该注解是作用于 POJO 等实体类上面的，是用来描述类的一些基本信息的。
- value：提供类的一个备用名，如果不设置，默认情况下将使用 class 类的名称
- description：对于类，提供一个详细的描述信息
- parent：这个属性用于描述的是类的一些父类信息
- discriminator：主要体现在断言当中
- subTypes：可以通过这个属性，指定我们想要使用的子类

用法：

@Data
@ApiModel(value = "TestDto", description = "测试dto")
public class TestDto {
	...
}

@ApiParam：用于描述 API 方法的参数信息。它通常用于标注方法参数
- value：描述参数的含义或用途。
- example：提供参数的示例值，帮助开发者理解参数的具体格式或内容。
- required：指定参数是否为必填项，默认为 false。
- allowableValues：定义参数的可选值范围，通常用于枚举类型或指定数值区间。
- dataType：显式指定参数的数据类型（如 String、Integer 等）。通常情况下，Swagger 会自动推断数据类型，但可以通过此属性手动指定。

用例：

public ResponseEntity<List<User>> getUsers(
    @ApiParam(value = "页码", example = "1") @RequestParam int page,
    @ApiParam(value = "每页大小", example = "10") @RequestParam int size) {
    
    // 方法实现
}

@ApiModelProperty：作用于 POJO 等实体类的属性值上
- value：提供字段的描述信息，说明该属性的用途或含义。
- example：指定字段的示例值，便于用户理解字段的数据格式和内容。
- required：指定字段是否为必填项，默认为 false。设置为 true 时，表明此字段在请求或响应中不可省略。
- allowableValues：定义字段的可选值，通常用于限定字段值范围，如枚举类型或指定数值区间。
- position：定义字段在文档中显示的顺序，数值越小，位置越靠前。
- dataType：指定字段的数据类型，如 String、Integer 等。一般情况下会自动推断，可以手动指定。
- notes：提供字段的额外说明信息，详细描述或补充字段的相关内容。

用例：

@Data
@ApiModel(value = "TestDto", description = "测试dto")
public class TestDto {

    @ApiModelProperty(value = "名称")
    private String name;

    @ApiModelProperty(value = "值")
    private String value;
}

@ApiOperationSupport ：该注解作用于Controller 层的方法上，是用来控制 接口参数的展示 和排序
- includeParameters：指定要包含的参数（其他未列出的参数不会展示）
- ignoreParameters：指定要忽略的参数（列出的参数不会展示）
- order：定义接口在文档中的显示顺序
- author：标注接口的作者信息

用例

假设有一个 DeptDto 类：

@Data
@ApiModel(value = "DeptDto", description = "部门信息")
public class DeptDto {

    @ApiModelProperty(value = "部门编号")
    private String deptNo;

    @ApiModelProperty(value = "部门名称")
    private String deptName;

    @ApiModelProperty(value = "父级部门编号")
    private String parentDeptNo;

    @ApiModelProperty(value = "状态")
    private Integer dataState;
}

控制器：

@ApiOperation("新增部门")
@ApiOperationSupport(includeParameters = {"deptDto.deptName", "deptDto.parentDeptNo", "deptDto.dataState"})
@PostMapping("/addDept")
public ResponseEntity<String> addDept(@RequestBody DeptDto deptDto) {
    return ResponseEntity.ok("新增部门成功");
}

📌 效果：

在 Swagger UI 中，/addDept 接口的请求参数 仅显示：
- deptDto.deptName
- deptDto.parentDeptNo
- deptDto.dataState
deptNo 不会显示，因为它没有被包含在 includeParameters 里。

网关聚合

在 Spring Cloud 中，我们可以将每个服务的接口文档全部都整合到 Gateway 中，也就是说我们只要从 Gateway 中打开接口文档就能够很方便的切换查看各个服务的接口文档。

操作：

knife4j使用-CSDN博客

Lusy

Knife4j

Knife4j 使用教程

简介

版本参考

基本使用

1. 导入相关依赖

2. 开启 knife4j 配置

3. 编写 knife4j 配置

4. 开启静态资源映射

5. 常用注解使用

网关聚合