springboot3 集成knife4j

knife4j介绍

Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案。

springdoc地址：OpenAPI 3 Library for spring-boot

Knife4j官网地址：Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j

环境介绍

java：17

SpringBoot：3.2.0

SpringCloud：2023.0.0

knife4j ： 4.4.0

引入maven配置

XML 复制代码

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

application.yml配置

java 复制代码

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.jilianyun.demo2.controller
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

Swagger3Config配置类

java 复制代码

package com.demo2.config;
 
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.OAuthFlow;
import io.swagger.v3.oas.models.security.OAuthFlows;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
 
/**
 * <p>Swagger 配置类</p>
 *
 * @author By: chegnxuyanshitang
 * Package com.demo2.config
 * Ceate Time 2024-04-22 10:25
 */
@Configuration
public class Swagger3Config extends WebMvcConfigurationSupport {
 
    /**
     * 设置静态资源映射
     *
     * @param registry
     */
    protected void addResourceHandlers (ResourceHandlerRegistry registry) {
        registry.addResourceHandler ("/doc.html").addResourceLocations ("classpath:/META-INF/resources/");
        registry.addResourceHandler ("/webjars/**").addResourceLocations ("classpath:/META-INF/resources/webjars/");
    }
 
    @Bean
    public OpenAPI apiInfo () {
        return new OpenAPI ()
                .info (new Info ()
                        .title ("demo服务")
                        .version ("1.0.0")
                        .description ("demo接口")
                        .license (new License ().name ("Apache 2.0")
                                .url ("http://www.yang.com/"))
                );
    }
}

DemoController类

java 复制代码

package com.demo2.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;
import java.util.Map;

/**
 * <p>DemoController</p>
 *
 * @author By: chengxuyuanshitang
 * Package com.demo2.controller
 * Ceate Time 2024-04-17 16:45
 */
@RefreshScope
@RestController
@Tag(name = "Demo接口", description = "Demo接口")
public class DemoController {


    @Autowired
    private JdbcTemplate jdbcTemplate;

    @GetMapping("demo")
    @Operation(summary = "demo接口", description = "demo接口")
    public String getMessage () {
        List<Map<String, Object>> maps = jdbcTemplate.queryForList ("SELECT * FROM users");

        System.out.println ("====================================");
        System.out.println (maps);
        System.out.println ("====================================");
        return message;
    }

   
}

启动服务，访问文档

访问Knife4j的文档地址：http://ip:port/doc.html即可查看文档

Knife4j版本参考

更名为Knife4j之前,原来的名称是叫swagger-bootstrap-ui，这是两种不一样风格的Ui,对比情况如下：

名称	开发语言&框架	状态	最后版本	风格
Knife4j	Java、JavaScript、Vue	持续更新中...	无	黑色
swagger-bootstrap-ui	Java、JavaScript、jQuery	停更	1.9.6	蓝色

nife4j从开源至今,目前主要经历版本的变化，分别如下：

版本	说明
1.0~1.9.6	名称是叫`swagger-bootstrap-ui`,蓝色风格Ui
1.9.6	蓝色皮肤风格,开始更名，增加更多后端模块
2.0~2.0.5	Ui基于Vue2.0+AntdV重写,黑色风格,参考示例，底层依赖的springfox框架版本是2.9.2,仅提供Swagger2规范的适配
2.0.6~2.0.9	底层springfox框架版本升级至2.10.5,,仅提供Swagger2规范的适配
3.0~3.0.3	底层依赖springfox框架版本升级至3.0.3,OpenAPI规范是v3,过度版本，建议开发者不要使用
4.0~	区分OpenAPI2和Swagger3的Maven坐标artifactId OpenAPI2规范服务端解析框架稳定在springfox2.10.5 OpenAPI3框架服务端解析跟随springdoc项目更新迭代建议开发者使用该版本

Spring Boot版本兼容性

Spring Boot版本	Knife4j Swagger2规范	Knife4j OpenAPI3规范
1.5.x~2.0.0	<Knife4j 2.0.0	>=Knife4j 4.0.0
2.0~2.2	Knife4j 2.0.0 ~ 2.0.6	>=Knife4j 4.0.0
2.2.x~2.4.0	Knife4j 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

Knife4j在之前的版本更新中，逐渐提供了一些服务端适配的增强特性功能。

但是开发者应该明白，不管是Swagger2规范还是OpenAPI3规范，Knife4j的最新版本的纯Ui版本，是可以适配Spring Boot所有版本的。

如果你不考虑使用Knife4j提供的服务端增强功能，引入Knife4j的纯Ui版本没有任何限制。只需要考虑不同的规范即可

Knife4版本参考地址： Knife4j版本参考 | Knife4j