最完整版-Springboot3集成Knife4j

一，前言

       在使用swagger-bootstrap-ui时我觉得它的样式和蓝色主色调不符合我的审美，所以我觉得使用一个更强的工具 Knife4j。Knife4j是一个用于SpringBoot和SpringCloud的增强Swagger的工具，提供黑色主题和更多配置选项。Knife4j在更名之前，原来的名称是叫swagger-bootstrap-ui，这是两种不一样风格的ui显示，将原来的蓝色变成炫酷的黑色模式。

二，Knife4j和swagger-bootstrap-ui对比

三，Spring Boot和Knife4j版本关系 

详细了解：https://doc.xiaominfo.com/docs/quick-start/start-knife4j-version

注意：

• Spring Boot 只支持 OpenAPI3 规范
• Knife4j提供的starter已经引用了springdoc-openapi的jar包，使用时需要避免jar包冲突
• Springboot3集成Knife4j时需要 JDK版本 >= 17

  四，集成步骤

  项目环境：

         JDK：17

         SpringBoot：3.0.13

         Knife4j：4.5.0

  1，引入依赖

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

  启动项目就可以查看界面了

  

  2，在application.yml中添加knife4j相关配置

  # springdoc-openapi项目配置
  springdoc:
    swagger-ui:
      #自定义swagger前端请求路径,输入http:localhost:8080/swagger-ui会自动重定向到swagger页面
      path: /swagger-ui
      tags-sorter: alpha
      operations-sorter: alpha
    api-docs:
      path: /v3/api-docs  #swagger后端请求地址
      enabled: true   #是否开启文档功能
    group-configs: #分组配置,可配置多个分组
      - group: 'default'             #分组名称
        paths-to-match: '/**'        #配置需要匹配的路径
        packages-to-scan: com.cms    #配置要扫描包的路径,一般配置到启动类所在的包名
      - group: 'admin-api'
        paths-to-match: '/**'
        packages-to-scan: com.cms

  

  添加knife4j的增强配置

  # knife4j的增强配置，不需要增强可以不配
  knife4j:
    enable: true    #开启knife4j,无需添加@EnableKnife4j注解
    setting:
      language: zh_cn   #中文
      swagger-model-name: 实体列表   #默认为：Swagger Models
    #开启Swagger的Basic认证功能,默认是false,开启后访问文档页面时会弹出用户名和密码输入框
    basic:
      enable: true
      # Basic认证用户名
      username: user
      # Basic认证密码
      password: 123456

  3，定义配置类WebMvcConfig

  package com.cms.config;
  import org.springframework.context.annotation.Configuration;
  import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
  import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
  /**
   * web层配置类,实现静态资源映射，将knife4j相关资源放行，保证生成的接口文档能够正常进行展示
   * @author Hva
   */
  @Configuration
  public class WebMvcConfig implements WebMvcConfigurer {
      /**
       * 设置静态资源映射
       */
      @Override
      public void addResourceHandlers(ResourceHandlerRegistry registry) {
          // 添加静态资源映射规则
          registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
          //配置 knife4j 的静态资源请求映射地址
          registry.addResourceHandler("/doc.html")
                  .addResourceLocations("classpath:/META-INF/resources/");
          registry.addResourceHandler("/webjars/**")
                  .addResourceLocations("classpath:/META-INF/resources/webjars/");
      }
  }

  4，定义Knife4j配置类

  package com.cms.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;
  /**
   * Knife4j整合Swagger3 Api接口文档配置类
   * @author Hva
   */
  @Configuration
  public class Knife4jConfig {
      /**
       * 创建了一个api接口的分组
       * 除了配置文件方式创建分组，也可以通过注册bean创建分组
       */
      @Bean
      public GroupedOpenApi adminApi() { 
          return GroupedOpenApi.builder()
                  // 分组名称
                  .group("app-api")
                  // 接口请求路径规则
                  .pathsToMatch("/**")
                  .build();
      }
      /**
       * 配置基本信息
       */
      @Bean
      public OpenAPI openAPI() {
          return new OpenAPI()
                  .info(new Info()
                          // 标题
                          .title("Knife4j整合Swagger3 Api接口文档")
                          // 描述Api接口文档的基本信息
                          .description("Knife4j后端接口服务...")
                          // 版本
                          .version("v1.0.0")
                          // 设置OpenAPI文档的联系信息，姓名，邮箱。
                          .contact(new Contact().name("Hva").email("Hva@163.com"))
                          // 设置OpenAPI文档的许可证信息，包括许可证名称为"Apache 2.0"，许可证URL为"http://springdoc.org"。
                          .license(new License().name("Apache 2.0").url("http://springdoc.org"))
                  );
      }
  }
  

  重启项目就可以看到自己配置的信息了

  

  五，基本使用

  引入下面测试需要的依赖

      org.projectlombok
      lombok
  
  
      com.baomidou
      mybatis-plus
      3.5.5
  

  1，创建实体类

  @Schema(description = "")： 标记实体类属性

  package com.cms.entry;
  import com.baomidou.mybatisplus.annotation.TableName;
  import io.swagger.v3.oas.annotations.media.Schema;
  import lombok.Data;
  /**
   * @author Hva
   */
  @Data
  @TableName("user")
  @Schema(description = "用户登录")
  public class UserVO {
      
      @Schema(description = "用户名")
      private String username;
      @Schema(description = "用户密码")
      private String password;
  }

  2，创建controller

  @Tag(name = “ ”)： 标记 controler 的类别
  @Operation(summary =“ ”)： 标记接口操作

  package com.cms.controller;
  import com.cms.entry.UserVO;
  import io.swagger.v3.oas.annotations.Operation;
  import io.swagger.v3.oas.annotations.tags.Tag;
  import org.springframework.web.bind.annotation.PostMapping;
  import org.springframework.web.bind.annotation.RequestBody;
  import org.springframework.web.bind.annotation.RestController;
  /**
   * @Author: Hva
   * @Description: 用户controller
   */
  @RestController
  @Tag(name = "用户controller")
  public class UserController {
      /**
       * 用户列表
       */
      @Operation(summary = "登录接口")
      @PostMapping("/login")
      public UserVO list(
              @RequestBody UserVO userVO
      ) {
         return userVO;
      }
  }

  3，启动项目

  标记的controller 会展示在左侧

  

  使用到的实体会在展示在 实体列表中 

  

  4，调试接口

  

  大功告成，至此，我们对 Knife4j 有了一定的了解和使用，想要了解更多就自己去探索吧！！！