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.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.5.0</version></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配置

packagecom.fs.config;importio.swagger.v3.oas.models.OpenAPI;importio.swagger.v3.oas.models.info.Contact;importio.swagger.v3.oas.models.info.Info;importio.swagger.v3.oas.models.info.License;importorg.springdoc.core.models.GroupedOpenApi;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;@ConfigurationpublicclassSwaggerConfig{@BeanpublicGroupedOpenApiadminApi(){// 创建了一个api接口的分组returnGroupedOpenApi.builder().group("admin-api")// 分组名称.pathsToMatch("/**")// 接口请求路径规则.build();}@BeanpublicOpenAPIopenAPI(){returnnewOpenAPI().info(newInfo()// 基本信息配置.title("fusApi")// 标题.description("Knife4j说明")// 描述Api接口文档的基本信息.version("v1")// 版本// 设置OpenAPI文档的联系信息，包括联系人姓名为"robin"，邮箱为"[email protected]"。.contact(newContact().name("robin").email("[email protected]"))// 设置OpenAPI文档的许可证信息，包括许可证名称为"Apache 2.0"，许可证URL为"http://springdoc.org"。.license(newLicense().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实体类

packagecom.fs.pojo;importio.swagger.v3.oas.annotations.media.Schema;importlombok.AllArgsConstructor;importlombok.Data;importlombok.NoArgsConstructor;@Data@AllArgsConstructor// 全参构造@NoArgsConstructor// 无参构造@Schema(description ="用户实体")publicclassUser{@Schema(description ="用户名称")privateString userName;@Schema(description ="密码")privateString password;@Schema(description ="邮箱")privateString email;@Schema(description ="年龄")privateint 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 的 官方文档。