开发者

Springboot3集成Knife4j的步骤以及使用(最完整版)

开发者 https://www.devze.com 2024-11-10 10:17 出处:网络 作者: 秋风~微凉
目录一,前言二,Knife4j和swagger-bootstrap-ui对比三,Spring Boot和Knife4j版本关系 四,集成步骤1,引入依赖2,在application.yml中添加knife4j相关配置3,定义配置类WebMvcConfig4,定义Knife4j配置类五,
目录
  • 一,前言
  • 二,Knife4j和swagger-bootstrap-ui对比
  • 三,Spring Boot和Knife4j版本关系 
  • 四,集成步骤
    • 1,引入依赖
    • 2,在application.yml中添加knife4j相关配置
    • 3,定义配置类WebMvcConfig
    • 4,定义Knife4j配置类
  • 五,基本使用
    • 1,创建实体类
    • 2,创建controller
    • 3,启动项目
    • 4,调试接口
  • 总结

    一,前言

    在使用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.0
    2.0 ~ 2.2Knife4j 2.0.0 ~ 2.0.6>= Knife4j 4.0.0
    2.2.x ~ 2.4.0Knife4j 2.0.6 ~ 2.0.9>= Knife4j 4.0.0
    2.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

    四,集成步骤

    项目环境:

           JDK:17

           SpringBoot:3.0.13

           Knife4j:4.5.0

    1,引入依赖

    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
        <version>4.5.0</www.devze.comversion>
    </dependency>

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

    Springboot3集成Knife4j的步骤以及使用(最完整版)

    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'   php          #分组名称
          paths-to-match: '/**'        #配置需要匹配的路径
          packages-to-scan: com.cms    #配置要扫描包的路径,一般配置到启动类所在的包名
        - group: 'admin-api'
          paths-to-match: '/**'
          packages-to-scan: com.cms

    Springboot3集成Knife4j的步骤以及使用(最完整版)

    添加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"))
                    );
        }
    }

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

    Springboot3集成Knife4j的步骤以及使用(最完整版)

    五,基本使用

    引入下面测试需要的依赖

    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
    </dependency>
    
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>myBATis-plus</artifactId>
        <version>3.5.5</version>
    </dependency>

    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 co编程客栈m.cms.entry.UserVO;
    import io.swagger.v3.oas.annotations.Operation;
    import io.swagger.v3.oas.annotations.tags.Tag;
    import org.springframework.web.bind.annotation.PostMjsapping;
    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 会展示在左侧

    Springboot3集成Knife4j的步骤以及使用(最完整版)

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

    Springboot3集成Knife4j的步骤以及使用(最完整版)

    4,调试接口

    Springboot3集成Knife4j的步骤以及使用(最完整版)

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

    总结

    到此这篇关于Springboot3集成Knife4j的步骤以及使用的文章就介绍到这了,更多相关Springboot3集成Knife4j内容请搜索编程客栈(www.devze.com)以前的文章或继续浏览下面的相关pCLAMQw文章希望大家以后多多支持编程客栈(www.devze.com)!

    0

    精彩评论

    暂无评论...
    验证码 换一张
    取 消