Knife4j自动生成API接口文档，springboot3配置Knife4j

Knife4j自动生成API接口文档

Knife4j 是一个为 Java 应用程序提供 API 文档生成和可视化的开源工具，它基于 Swagger 和 OpenAPI 规范。以下是 Knife4j 的基本使用文档，包括安装、配置和使用指南。

1. 概述

Knife4j 是为 Java 应用程序提供 API 文档生成、测试、监控的增强解决方案，它整合了 Swagger UI、Swagger Editor、Swagger Codegen 的功能，同时提供了更友好的 API 管理界面。

2. 环境准备

• JDK 17 或更高版本
• Maven 或 Gradle 作为构建工具
• 使用的springboot3,对于2的如何进行使用参考官方文档:https://doc.xiaominfo.com/docs/quick-start

注意:

• Spring Boot 3 只支持OpenAPI3规范
• Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突
• JDK版本必须 >= 17

3. 添加 Knife4j 依赖

3.1 Maven

在项目的 pom.xml 文件中添加 Knife4j 的依赖。

<dependency>
    <groupId>com.github.xiaoymingroupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starterartifactId>
    <version>4.5.0version>
dependency>

3.2 Gradle

在项目的 build.gradle 文件中添加 Knife4j 的依赖。

implementation("com.github.xiaoymin:knife4j-openapi3-jakarta-spring-boot-starter:4.4.0")

4. 配置knefe4j

在springboot3中进行配置knefe4j有2种配置的方式,可以完全的在applacation.yml配置文件中进行配置也可以进行创建SwaggerConfig配置类进行配置

4.1 SwaggerCongfig配置

package com.fs.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public GroupedOpenApi adminApi() {      // 创建了一个api接口的分组
        return GroupedOpenApi.builder()
                .group("admin-api")         // 分组名称
                .pathsToMatch("/**")  // 接口请求路径规则
                .build();
    }
    @Bean
    public OpenAPI openAPI(){
        return new OpenAPI()
                .info(new Info() // 基本信息配置
                        .title("fusApi") // 标题
                        .description("Knife4j说明") // 描述Api接口文档的基本信息
                        .version("v1") // 版本
                        // 设置OpenAPI文档的联系信息，包括联系人姓名为"robin"，邮箱为"[email protected]"。
                        .contact(new Contact().name("robin").email("[email protected]"))
                        // 设置OpenAPI文档的许可证信息，包括许可证名称为"Apache 2.0"，许可证URL为"http://springdoc.org"。
                        .license(new License().name("Apache 2.0").url("http://springdoc.org"))
                );

    }
}

4.2 配置文件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: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.xiaominfo.knife4j.demo.web # 扫描的包，注意改成自己的包
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

5. 书写接口文档

常用的核心注解

注解	描述
@OpenAPIDefinition	定义 OpenAPI 规范的基本信息，如 API 的标题、版本、服务器等
@Operation	用于描述 API 操作（端点），包括操作的摘要、描述、请求和响应等信息
@ApiResponse	定义操作的响应，包括响应的状态码、描述和响应模型等信息
@Parameter	定义操作的参数，包括路径参数、查询参数、请求头参数等
@PathVariable	定义路径参数，用于提取 URL 中的变量
@RequestParam	定义查询参数，用于从请求中获取参数的值
@ApiParam	在方法参数上使用，用于描述参数的含义和约束
@ApiResponses	在控制器类上使用，为多个操作定义通用的响应规范
@ApiResponseExtension	在 @Operation 或 @ApiResponse 上使用，用于扩展响应信息
@SecurityRequirement	定义操作所需的安全要求，如需要的身份验证方案、安全范围等
@SecurityScheme	定义安全方案，包括认证方式（如 Basic、OAuth2 等）、令牌 URL、授权 URL 等
@Tags	定义操作的标签，用于对操作进行分类和组织
@Hidden	在文档中隐藏标记的操作或参数，可以用于隐藏一些内部或不需要在文档中展示的部分
@Extension	用于为生成的 OpenAPI 文档添加自定义的扩展信息，可以在文档中增加额外的元数据或自定义字段
@RequestBodySchema	定义请求体的数据模型，允许对请求体进行更细粒度的描述和约束，如属性的名称、类型、格式、必填性等
@ApiResponseSchema	定义响应的数据模型，允许对响应体进行更细粒度的描述和约束，如属性的名称、类型、格式、必填性等
@ExtensionProperty	在 @Extension 注解上使用，用于定义自定义扩展的属性，可以添加额外的元数据或自定义字段到生成的 OpenAPI 文档中

5.1 conttoller层

@RestController
@Tag(name = "首页") // Api的模块名称
@RequestMapping("/test")
public class IndexController {
    @GetMapping("/getUser")  // 请求路径
    @Operation(summary = "获取用户") // Api的描述
    public User getUser(@Parameter(name = "userName",description = "用户名称",in = ParameterIn.QUERY)String userName) {
        return new User(userName, "123456", "[email protected]", 18);
    }
    @PostMapping("/addUser")
    @Operation(summary = "新增用户")
    public Boolean addUser(@RequestBody  User user) {
        return true;
    }
}

5.2 User实体类

package com.fs.pojo;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@AllArgsConstructor // 全参构造
@NoArgsConstructor // 无参构造
@Schema(description = "用户实体")
public class User {
    @Schema(description = "用户名称")
    private String userName;
    @Schema(description = "密码")
    private String password;
    @Schema(description = "邮箱")
    private String email;
    @Schema(description = "年龄")
    private int age;
}

这个实体类会进行展示在 Swagger Model 中进行展示。

6. 启动应用并访问文档

启动你的 Spring Boot 应用，然后通过浏览器访问 http://localhost:8080/swagger-ui.html（假设应用运行在 8080 端口），你应该能看到 Swagger UI 界面，并且可以查看和测试 API。访问http://localhost:8080/doc.html你能够看见Knif4j美化后的页面.

7. 高级特性

Knife4j 还支持多种高级特性，如全局配置、个性化设置、增强模式等。具体使用方法可以参考 Knife4j 的官方文档。

8. 注意事项

• Knife4j 与 Swagger 2.x 版本兼容。
• Knife4j 需要与 Spring Boot 应用一起使用。
• boot2和boot3使用的knife4j引入的依赖不同

9. 官方文档

更多详细信息和高级使用，请参考 Knife4j 的 官方文档。