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 的依赖。

    
        com.github.xiaoymin
        knife4j-openapi3-jakarta-spring-boot-starter
        4.5.0
    
    

    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"，邮箱为"robin@gmail.com"。
                            .contact(new Contact().name("robin").email("robin@gmail.com"))
                            // 设置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", "123@qq.com", 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 的 官方文档。