0
0

最完整版-Springboot3集成Knife4j

一，前言

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

二，Knife4j和swagger-bootstrap-ui对比

工具状态风格配置Knife4j持久更新黑色主题支持配置文件编写配置项swagger-bootstrap-ui停更，2.x后更名为Knife4j蓝色主题不支持

三，Spring Boot和**Knife4j版本关系 **

Spring Boot版本Knife4j Swagger 2规范Knife4j OpenAPI 3规范1.5.x ~ 2.0.0< Knife4j 2.0.0>= Knife4j 4.0.02.0 ~ 2.2Knife4j 2.0.0 ~ 2.0.6>= Knife4j 4.0.02.2.x ~ 2.4.0Knife4j 2.0.6 ~ 2.0.9>= Knife4j 4.0.02.4.0 ~ 2.7.x>= Knife4j 4.0.0>= Knife4j 4.0.0>= 3.0>= Knife4j 4.0.0>= Knife4j 4.0.0
详细了解：https://doc.xiaominfo.com/docs/quick-start/start-knife4j-version

注意：

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

四，集成步骤

项目环境：

  1.    JDK：17
  3.    SpringBoot：3.0.13
  5.    Knife4j：4.5.0

1，引入依赖

  1. <dependency>
  2.     <groupId>com.github.xiaoymin</groupId>
  3.     <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
  4.     <version>4.5.0</version>
  5. </dependency>

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

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

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

添加knife4j的增强配置

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

3，定义配置类WebMvcConfig

  1. package com.cms.config;
  3. import org.springframework.context.annotation.Configuration;
  4. import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
  5. import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
  7. /**
  8.  * web层配置类,实现静态资源映射，将knife4j相关资源放行，保证生成的接口文档能够正常进行展示
  9.  * @author Hva
  10.  */
  11. @Configuration
  12. public class WebMvcConfig implements WebMvcConfigurer {
  14.     /**
  15.      * 设置静态资源映射
  16.      */
  17.     @Override
  18.     public void addResourceHandlers(ResourceHandlerRegistry registry) {
  19.         // 添加静态资源映射规则
  20.         registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
  21.         //配置 knife4j 的静态资源请求映射地址
  22.         registry.addResourceHandler("/doc.html")
  23.                 .addResourceLocations("classpath:/META-INF/resources/");
  24.         registry.addResourceHandler("/webjars/**")
  25.                 .addResourceLocations("classpath:/META-INF/resources/webjars/");
  26.     }
  27. }

4，定义Knife4j配置类

  1. package com.cms.config;
  3. import io.swagger.v3.oas.models.OpenAPI;
  4. import io.swagger.v3.oas.models.info.Contact;
  5. import io.swagger.v3.oas.models.info.Info;
  6. import io.swagger.v3.oas.models.info.License;
  7. import org.springdoc.core.models.GroupedOpenApi;
  8. import org.springframework.context.annotation.Bean;
  9. import org.springframework.context.annotation.Configuration;
  11. /**
  12.  * Knife4j整合Swagger3 Api接口文档配置类
  13.  * @author Hva
  14.  */
  15. @Configuration
  16. public class Knife4jConfig {
  18.     /**
  19.      * 创建了一个api接口的分组
  20.      * 除了配置文件方式创建分组，也可以通过注册bean创建分组
  21.      */
  22.     @Bean
  23.     public GroupedOpenApi adminApi() { 
  24.         return GroupedOpenApi.builder()
  25.                 // 分组名称
  26.                 .group("app-api")
  27.                 // 接口请求路径规则
  28.                 .pathsToMatch("/**")
  29.                 .build();
  30.     }
  32.     /**
  33.      * 配置基本信息
  34.      */
  35.     @Bean
  36.     public OpenAPI openAPI() {
  37.         return new OpenAPI()
  38.                 .info(new Info()
  39.                         // 标题
  40.                         .title("Knife4j整合Swagger3 Api接口文档")
  41.                         // 描述Api接口文档的基本信息
  42.                         .description("Knife4j后端接口服务...")
  43.                         // 版本
  44.                         .version("v1.0.0")
  45.                         // 设置OpenAPI文档的联系信息，姓名，邮箱。
  46.                         .contact(new Contact().name("Hva").email("Hva@163.com"))
  47.                         // 设置OpenAPI文档的许可证信息，包括许可证名称为"Apache 2.0"，许可证URL为"http://springdoc.org"。
  48.                         .license(new License().name("Apache 2.0").url("http://springdoc.org"))
  49.                 );
  50.     }
  51. }

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

五，基本使用

引入下面测试需要的依赖

  1. <dependency>
  2.     <groupId>org.projectlombok</groupId>
  3.     <artifactId>lombok</artifactId>
  4. </dependency>
  6. <dependency>
  7.     <groupId>com.baomidou</groupId>
  8.     <artifactId>mybatis-plus</artifactId>
  9.     <version>3.5.5</version>
  10. </dependency>

1，创建实体类

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

  1. package com.cms.entry;
  3. import com.baomidou.mybatisplus.annotation.TableName;
  4. import io.swagger.v3.oas.annotations.media.Schema;
  5. import lombok.Data;
  7. /**
  8.  * @author Hva
  9.  */
  10. @Data
  11. @TableName("user")
  12. @Schema(description = "用户登录")
  13. public class UserVO {
  14.     
  15.     @Schema(description = "用户名")
  16.     private String username;
  18.     @Schema(description = "用户密码")
  19.     private String password;
  21. }

2，创建controller

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

  1. package com.cms.controller;
  3. import com.cms.entry.UserVO;
  4. import io.swagger.v3.oas.annotations.Operation;
  5. import io.swagger.v3.oas.annotations.tags.Tag;
  6. import org.springframework.web.bind.annotation.PostMapping;
  7. import org.springframework.web.bind.annotation.RequestBody;
  8. import org.springframework.web.bind.annotation.RestController;
  10. /**
  11.  * @Author: Hva
  12.  * @Description: 用户controller
  13.  */
  14. @RestController
  15. @Tag(name = "用户controller")
  16. public class UserController {
  17.     /**
  18.      * 用户列表
  19.      */
  20.     @Operation(summary = "登录接口")
  21.     @PostMapping("/login")
  22.     public UserVO list(
  23.             @RequestBody UserVO userVO
  24.     ) {
  25.        return userVO;
  26.     }
  27. }

3，启动项目

标记的controller 会展示在左侧

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

4，调试接口

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

标签： spring boot bootstrap
本文转载自: https://blog.csdn.net/qq_62398643/article/details/141418967
版权归原作者 秋风~微凉 所有， 如有侵权，请联系我们删除。
登录后发布评论

“最完整版-Springboot3集成Knife4j”的评论:

还没有评论
关于作者
...
overfit同步小助手
文章同步
相关阅读

网络安全法-网络运行安全

使用selenium/drissionpage时如何阻止chrome自动跳转http到https

docker desktop 里部署的Open WebUI 管理员密码忘记了的处理方法

在ubuntu20.04中搭建onsite比赛运行环境

利用开源的低代码表单设计器FcDesigner高效管理和渲染复杂表单结构

Kafka学习笔记

【前端】浏览器输入url到页面呈现发生了什么？

文章导航
没有找到文章内容分段。。。