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配置

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

application.yml配置

springdoc:swagger-ui:path: /swagger-ui.htmltags-sorter: alphaoperations-sorter: alphaapi-docs:path: /v3/api-docsgroup-configs:- group: 'default'paths-to-match: '/**'packages-to-scan: com.jilianyun.demo2.controller
# knife4j的增强配置，不需要增强可以不配
knife4j:enable: truesetting:language: zh_cn

Swagger3Config配置类

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/");}@Beanpublic 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类

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 {@Autowiredprivate 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