【6】Spring Boot 3 集成组件：knift4j+springdoc+swagger3

目录

  • 【6】Spring Boot 3 集成组件：knift4j+springdoc+swagger3
    • OpenApi规范
    • SpringFox + Swagger3
      • SpringFox工具（`不推荐`）
    • Springdoc（`推荐`）
      • 从SpringFox迁移
      • 引入依赖
      • 配置
      • jAVA Config 配置
      • 扩展配置：spring security
      • 启动
    • Knift4j + Spring doc
      • 引用依赖
      • 配置
      • 启动
    • 参考资料

个人主页: 【⭐️个人主页】
需要您的【💖 点赞+关注】支持 💯

【6】Spring Boot 3 集成组件：knift4j+springdoc+swagger3

📖 本文核心知识点：

  • openApi 规范
  • Swagger3
  • springdoc
  • knift4j+springdoc+swagger3

OpenApi规范

其实OpenAPI规范（也称为 Swagger 3.x 规范）是一种用于描述·RESTful AP·I的标准化格式，它定义了如何描述API的基本信息、结构、参数、响应等方面的规范。·OpenAPI规范·以机器可读的方式定义了·RESTful API·的结构和特征，支持自动生成文档、客户端与服务端代码、Mock Server和测试工具等。

OpenAPI规范最初由开发Swagger的团队在2010年推出，从Swagger 2.0开始，Swagger规范被正式更名为OpenAPI规范，并得到了许多社区的支持和贡献。OpenAPI规范采用JSON或YAML格式编写，并支持多种数据类型，可以描述API的基本信息、路径、HTTP方法、参数、响应等各种细节。通过遵循OpenAPI规范，开发者可以快速定义和构建RESTful API，并且可以生成相应的文档和代码来帮助他们更快地开发与测试API。同时，OpenAPI规范还可以促进不同系统之间的交互和集成，因为根据规范定义的API可以被多个客户端程序和服务端程序所理解和使用。

OpenAPI阶段的Swagger也被称为Swagger 3.0。在Swagger 2.0后，Swagger规范正式更名为OpenAPI规范，并且根据OpenAPI规范的版本号进行了更新。因此，Swagger 3.0对应的就是OpenAPI 3.0版本，它是Swagger在OpenAPI阶段推出的一个重要版本。与前几个版本相比，Swagger 3.0更加强调对RESTful API的支持和规范化，提供了更丰富和灵活的定义方式，并且可以用于自动生成文档、客户端代码、服务器代码和测试工具等。

SpringFox + Swagger3

【HOME】Swagger.io
Swagger它最初由Tony Tam在2011年创建，并在之后被SmartBear Software公司收购。在过去几年中，Swagger经历了许多重大的更新和变化，

其发展史大概可以分为以下几个阶段：
①：Swagger 1.x 阶段（2011-2014年）
Swagger最初是一个简单的API文档生成工具，通过对JAX-RS和Jersey注解的支持自动生成API文档，使得API文档的维护变得更加容易。
在这个阶段，Swagger还没有完全成熟，只能支持基本的API描述和文档生成。
②：Swagger 2.x 阶段（2014-2017年）
在Swagger 2.x阶段，Swagger发生了重大变化。它不再仅仅是一个文档生成工具，而是一个完整的API开发和管理平台。Swagger 2.x加入了强大的注解支持，可以描述API的细节信息，如请求参数、返回类型等，以及定义RESTful API的元数据，如API描述、标签等。
此外，Swagger 2.x还引入了OpenAPI规范，在API定义方面有了更严格的标准和规则。
③：OpenAPI 阶段（2017-至今）（也被称为Swagger 3.x）
在2017年，Swagger 2.x的规范成为了Linux基金会旗下的OpenAPI规范。这标志着Swagger从一款工具演变成为了一个开放且标准的API定义框架。OpenAPI规范不仅继承了Swagger 2.x的特性，还提供了更加全面和严格的API定义规范，并且扩展了对非RESTful API的支持

随着OpenAPI规范的普及，越来越多的API开发者开始使用Swagger/OpenAPI来开发、测试和文档化他们的RESTful API。
　所以，随着Linux基金会旗下的OpenAPI收购了Swagger2.x后对其进行了更严格的规范，又进行了各种优化
　所以我们也可以称OpenAPI是一个全新的Swagger3.x，因为OpenAPI对其作了更多的优化和规范。
除了上述几个主要阶段之外，还有一些其他重要的事件和版本，如Swagger UI、Swagger Codegen、SwaggerHub等等。
这些工具和服务进一步扩展了Swagger的功能，使其成为了一个更加完整、强大和易于使用的API定义和管理平台。

SpringFox工具（不推荐）

Springfox是一套可以帮助Java开发者自动生成API文档的工具，它是基于Swagger 2.x基础上开发的。Swagger已经成为了RESTful API文档生态系统的事实标准，而Springfox是一个用于集成Swagger2.x到Spring应用程序中的库。而且Springfox提供了一些注解来描述API接口、参数和返回值，并根据这些信息生成Swagger UI界面，从而方便其他开发人员查看和使用您的API接口。此外，Springfox还支持自动生成API文档和代码片段，简化了开发人员的工作量。除了集成Swagger 2.x，Springfox还提供了一些额外功能，例如自定义Swagger文档、API版本控制、请求验证等等。这些功能使得Springfox可以胜任各种类型和规模的应用程序，同时还可以提高代码质量和开发效率。总之，Springfox是一个非常有用的工具，它可以帮助Java开发者快速、简单地集成Swagger2.x，并为他们的应用程序生成高质量的API文档。无论您开发的是大型企业应用程序还是小型服务，使用Springfox都能够提高团队的生产力和代码质量。

🅰️ 注意：但是随着时间的推移，Swagger2.x终究成为历史，所以我们可以看出springfox-boot-starter的坐标从3.0.0版本（2020年7月14日）开始就一直没有更新；也得注意的是springfox-swagger2坐标和springfox-boot-start是一样的，但springfox-boot-start只有3.0.0版本。这里我就不在使用Swagger2.x版本，具体可以在网上找到许多，因为大部分的网上资料都是Swagger2.x的方式。

Springdoc（推荐）

SpringDoc对应坐标是springdoc-openapi-ui，它是一个集成Swagger UI和ReDoc的接口文档生成工具，在使用上与springfox-boot-starter类似，但提供了更为灵活、功能更加强大的工具。其中除了可以生成Swagger UI风格的接口文档，还提供了ReDoc的文档渲染方式，可以自动注入OpenAPI规范的JSON描述文件，支持OAuth2、JWT等认证机制，并且支持全新的OpenAPI 3.0规范。

SpringDoc是基于OpenAPI 3.0规范构建的，因此推荐在Spring Boot 2.4及以上版本中使用springdoc-openapi-ui库来集成Swagger3.x。在这些版本中，springdoc-openapi-ui库已被广泛应用，并且得到了社区的大力支持和推广。而在Spring Boot 2.3及其以下版本，可以使用springfox-boot-starter库来集成Swagger2.x。

SpringDoc是有着更加先进的技术架构和更好的扩展性，使得其逐渐取代了springfox-boot-starter工具包，成为了当前Spring Boot生态中最受欢迎的API文档工具之一。同时springdoc-openapi-ui还拥有更为完善的开发文档和社区支持，从而吸引了越来越多的开发者加入到这个项目中。因此作为一个Spring Boot开发者，如果想要快速、方便地生成符合OpenAPI 3.0规范的接口文档，建议使用springdoc-openapi-ui这个优秀的工具。

SpringDoc是一款可以结合SpringBoot使用的API文档生成工具，基于OpenAPI 3，目前在Github上已有1.7K+Star，更新发版还是挺勤快的，是一款更好用的Swagger库！值得一提的是SpringDoc不仅支持Spring WebMvc项目，还可以支持Spring WebFlux项目，甚至Spring Rest和Spring Native项目，总之非常强大，下面是一张SpringDoc的架构图。
在这里插入图片描述

从SpringFox迁移

SpringFoxSpringDoc
@Api@Tag
@ApiIgnore@Parameter(hidden = true)or@Operation(hidden = true)or@Hidden
@ApiImplicitParam@Parameter
@ApiImplicitParams@Parameters
@ApiModel@Schema
@ApiModelProperty@Schema
@ApiOperation(value = “foo”, notes = “bar”)@Operation(summary = “foo”, description = “bar”)
@ApiParam@Parameter
@ApiResponse(code = 404, message = “foo”)ApiResponse(responseCode = “404”, description = “foo”)

引入依赖

Maven

<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
   <version>2.2.0</version>
</dependency>

Gradle

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

配置

application.yaml中增加springdoc的配置

# ======== spring doc api document =========
springdoc:
  swagger-ui:
    # 开启开关
    enabled: true
    #    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
    syntax-highlight:
      activated: true
  api-docs:
    path: /v3/api-docs
    enabled: true
  # 分组配置
  group-configs:
    - displayName: "API组"
      group: API
      paths-to-match: /**
      ## 修改成自己的api的包路径【包含RestController的目录]
      packages-to-scan: com.kongxiang.studyspring3.api
#    - displayName: "Controller组"
#      group: Controller
#      paths-to-match: /**
#      packages-to-scan: com.kongxiang.studyspring3.facade.controller

jAVA Config 配置

如果希望提供更明确的信息，请额外使用JavaConfig配置

@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("孔翔的项目spring3")
                        .description("SpringDoc API ")
                        .version("v1.0.0")
                        .license(new License().name("Apache 2.0").url("https://blog.csdn.net/k316378085?type=blog")))
                .externalDocs(new ExternalDocumentation()
                        .description("CSDN: 主页")
                        .url("https://blog.csdn.net/k316378085?type=blog"));
    }

}

扩展配置：spring security

需要把springdoc相关的接口权限放开访问权限

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig extends WebSecurityConfigurerAdapter {                                              

    @Override
    protected void configure(HttpSecurity httpSecurity) throws Exception {
        httpSecurity.csrf()// 由于使用的是JWT，我们这里不需要csrf
                .disable()
                .sessionManagement()// 基于token，所以不需要session
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
                .and()
                .authorizeRequests()
                .antMatchers(HttpMethod.GET, // Swagger的资源路径需要允许访问
                        "/",   
                        "/swagger-ui.html",
                        "/swagger-ui/",
                        "/*.html",
                        "/favicon.ico",
                        "/**/*.html",
                        "/**/*.css",
                        "/**/*.js",
                        "/swagger-resources/**",
                        "/v3/api-docs/**"
                )
                .permitAll()
                .antMatchers("/login")// 对登录注册要允许匿名访问
                .permitAll()
                .antMatchers(HttpMethod.OPTIONS)//跨域请求会先进行一次options请求
                .permitAll()
                .anyRequest()// 除上面外的所有请求全部需要鉴权认证
                .authenticated();
        
    }

}

// -----------------------------------------------------------------------------
// 增加 java配置


@Configuration
public class SpringDocConfig {
    /** Jwt 认证头名 */
    private static final String SECURITY_SCHEME_NAME = "BearerAuth";
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("孔翔的项目spring3")
                        .description("SpringDoc API ")
                        .version("v1.0.0")
                        .license(new License().name("Apache 2.0").url("https://blog.csdn.net/k316378085?type=blog")))
                .externalDocs(new ExternalDocumentation()
                        .description("CSDN: 主页")
                        .url("https://blog.csdn.net/k316378085?type=blog"))
                // spring security jwt auth
                .addSecurityItem(new SecurityRequirement().addList(SECURITY_SCHEME_NAME))
                .components(new Components()
                        .addSecuritySchemes(SECURITY_SCHEME_NAME,
                                new SecurityScheme()
                                        .name(SECURITY_SCHEME_NAME)
                                        .type(SecurityScheme.Type.HTTP)
                                        .scheme("bearer")
                                        .bearerFormat("JWT")));


    }

}

启动

启动springboot3项目并访问本地路径http://localhost:8080/swagger-ui.html 在这里插入图片描述

Knift4j + Spring doc

knift4j Doc

提示
Spring Boot 3 只支持OpenAPI3规范
Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突
JDK版本必须 >= 17
详细Demo请参考knife4j-spring-boot3-demo

引用依赖

Maven

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

Gradle

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

配置

# ======== spring doc api document =========
springdoc:
  swagger-ui:
    # 开启开关
    enabled: true
    #    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
    syntax-highlight:
      activated: true
  api-docs:
    path: /v3/api-docs
    enabled: true
  group-configs:
    - displayName: "API组"
      group: API
      paths-to-match: /**
      packages-to-scan: com.kongxiang.studyspring3.api
#    - displayName: "Controller组"
#      group: Controller
#      paths-to-match: /**
#      packages-to-scan: com.kongxiang.studyspring3.facade.controller


# ========== knife4j
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  documents:
    name: kongxiang
  setting:
    language: zh_cn
  # 开启生产环境屏蔽
  production: false
  # 开启Swagger的Basic认证功能,默认是false
  basic:
    enable: true
    # Basic认证用户名
    username: test
    # Basic认证密码
    password: 123

启动

访问localhost:8080/doc.html
在这里插入图片描述

参考资料

项目地址：https://github.com/springdoc/springdoc-openapi
官方文档：https://springdoc.org/

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：/a/150708.html

如若内容造成侵权/违法违规/事实不符，请联系我们进行投诉反馈qq邮箱809451989@qq.com，一经查实，立即删除！

相关文章

istio安装文档

istio安装文档

1、重装命令 istioctl manifest generate --set profiledemo | kubectl delete --ignore-not-foundtrue -f - 2、下载 参考&#xff1a;02、istio部署到k8s中 - 简书 (jianshu.com) 参考 Istio / 入门 curl -L https://istio.io/downloadIstio | ISTIO_VERSION1.20.0 TAR…
阅读更多...
[工业自动化-22]：西门子S7-15xxx编程 - 软件编程 - 如何PLC建立用户界面: SIMATIC 面板式HMI 或工控机PC HMI

[工业自动化-22]：西门子S7-15xxx编程 - 软件编程 - 如何PLC建立用户界面: SIMATIC 面板式HMI 或工控机PC HMI

目录 前言&#xff1a; 一、PLC&#xff08;可编程逻辑控制器&#xff09;的用户界面支持方式 1.1 概述 1.2 西门子&#xff08;Siemens&#xff09;的人机界面&#xff08;HMI&#xff09;支持多种类型 1.3 PC HMI VS SIMATIC HMI 二、PC—HMI—PLC连接架构的实现 三、…
阅读更多...
OpenAI与微软合作，构建 ChatGPT 5 模型；10天准确天气预报

OpenAI与微软合作，构建 ChatGPT 5 模型；10天准确天气预报

&#x1f989; AI新闻 &#x1f680; OpenAI与微软合作&#xff0c;构建 ChatGPT 5 模型&#xff0c;下一代人工智能或拥有超级智能 摘要&#xff1a;OpenAI首席执行官 Sam Altman 在接受采访时表示&#xff0c;OpenAI正在与微软合作构建下一代人工智能模型 ChatGPT 5&#x…
阅读更多...
Winodws核心编程 多线程

Winodws核心编程 多线程

目录 一、基本概念 二、线程创建函数 三、Windows内核对象与句柄 四、简单的多线程案例 五、线程同步 - 互斥对象 六、多线程实现群聊的服务端和客户端 七、线程同步 - 事件对象 八、事件对象 与 互斥对象区别 九、线程同步 - 信号量 十、线程同步 - 关键代码段 十一…
阅读更多...
SpringSecurity6从入门到上天系列第六篇：解决这个问题为什么在引入SpringSecurity之后所有的请求都需要先做登录认证才可以进行访问呢

SpringSecurity6从入门到上天系列第六篇：解决这个问题为什么在引入SpringSecurity之后所有的请求都需要先做登录认证才可以进行访问呢

文章目录 问题引入 1&#xff1a;问题阐述 2&#xff1a;问题分析 一&#xff1a;从SpringBoot的自动装配 1&#xff1a;SpringBootApplication介绍 2&#xff1a;自动装配的核心方法 3&#xff1a;核心方法的调用路径 4&#xff1a;SpringSecurity核心配置 5&#xf…
阅读更多...
每日一题：编写程序，使程序分别输出两个整数的加减乘除运算结果

每日一题：编写程序，使程序分别输出两个整数的加减乘除运算结果

文章目录 每日一题一、编写程序&#xff0c;使程序分别输出两个整数的加减乘除运算结果以下是一个使用 Java 编写的程序&#xff0c;可以输出两个整数的加减乘除运算结果&#xff1a;以下是一个简单的 Python 程序&#xff0c;可以计算两个整数的加减乘除运算结果&#xff1a; …
阅读更多...
Python---数据序列类型之间的相互转换

Python---数据序列类型之间的相互转换

list()方法&#xff1a;把某个序列类型的数据转化为列表 # 1、定义元组类型的序列 tuple1 (10, 20, 30) print(list(tuple1))# 2、定义一个集合类型的序列 set1 {a, b, c, d} print(list(set1))# 3、定义一个字典 dict1 {name:刘备, age:18, address:蜀中} print(list(dict1…
阅读更多...
JavaScript的函数的形参与实参是怎么回事

JavaScript的函数的形参与实参是怎么回事

0 写在前面 此文给小白看的&#xff0c;如果不是可以直接关闭 1 讲解 例如JavaScript中定义函数 //定义函数 function 方法名(形参){方法体-->使用形参}//使用函数 方法名字(实参)具体干了什么呢&#xff1f;此处以伪代码举例 //定义函数 function eat(A,B){A 去 B 家吃…
阅读更多...
iOS性能优化

iOS性能优化

了解屏幕成像的原理。 有一个电子枪然后在很多横轴方向上 发射电子&#xff0c;不同横轴的电子枪根据显示器中的硬件时钟产生一系列的定时信号&#xff0c;以此来让电子以不同的时间发射出去 这些电子一瞬间的运动形成了一帧动画。 CPU优化&#xff1a; 1.文本计算优化 如果一…
阅读更多...
第十九章 Java绘图

第十九章 Java绘图

第十九章 java绘图 19.1 java绘图类 绘图时高级程序设计中非常重要的技术&#xff0c;例如&#xff0c;应用程序可以绘制闪屏图片&#xff0c;背景图片&#xff0c;组件外观等等&#xff0c;Web程序可以绘制统计图&#xff0c;数据库存储图片资源等&#xff0c;真骨耸为“一…
阅读更多...
5、鸿蒙项目远程调试

5、鸿蒙项目远程调试

一、注册华为账号&#xff0c; 如果是华为手机&#xff0c;并注册了账号可能跳过此步骤&#xff0c;如果使用邮箱注册&#xff0c;此邮箱一定是要正确的邮箱&#xff0c;此处需要使用邮箱获取验证码 注册地址&#xff1a;‎ 1、进入注册页面&#xff0c;输入手机号等信息后点…
阅读更多...
蒙HarmonyOS从零实现类微信app效果第二篇，我的+发现页面实现

蒙HarmonyOS从零实现类微信app效果第二篇，我的+发现页面实现

本着不拖更的原则&#xff0c;今天上新了&#xff0c;今天实现了类微信app的发现页和我的页面。先看效果。 效果是不是看着还不错。其实这两个页面功能实现还是比较简单的&#xff0c;接下来还是老规矩&#xff0c;先进行页面的拆分和代码实现&#xff0c;然后进行相关我认为比…
阅读更多...
HarmonyOS开发：动态共享包的依赖问题

HarmonyOS开发：动态共享包的依赖问题

一、共享包的依赖方式 在需要依赖的模块包目录下oh-package.json5文件中添加依赖&#xff1a; "dependencies": {"ohos/srpaasUI": "file:../../srpaasUI","ohos/srbusiness": "file:../../feature/srbusiness"} 引入之后…
阅读更多...
测试问题—APP闪退

测试问题—APP闪退

APP闪退的原因有以下几种&#xff1a; APP本身的程序错误或bug&#xff0c;导致在运行过程中出现异常或崩溃&#xff0c;例如内存泄漏、空指针、死循环等。这种情况下&#xff0c;需要开发者对APP进行调试和修复&#xff0c;或者用户更新到最新版本的APP。 APP与系统或其他APP…
阅读更多...
Zookeeper学习笔记（1）—— 基础知识

Zookeeper学习笔记（1）—— 基础知识

Zookeeper概述 Zookeeper 是一个开源的分布式的&#xff0c;为分布式框架提供协调服务的 Apache 项目 工作机制 Zookeeper从设计模式角度来理解&#xff1a;是一个基于观察者模式设计的分布式服务管理框架&#xff0c;它负责存储和管理大家都关心的数据&#xff0c;然后接受…
阅读更多...
基于PHP的化妆品销售网站，MySQL数据库，PHPstudy，前台用户+后台管理，完美运行，有一万多字论文

基于PHP的化妆品销售网站，MySQL数据库，PHPstudy，前台用户+后台管理，完美运行，有一万多字论文

目录 演示视频 基本介绍 论文截图 系统截图 演示视频 基本介绍 基于PHP的化妆品销售网站&#xff0c;MySQL数据库&#xff0c;PHPstudy&#xff0c;原生PHP&#xff0c;前台用户后台管理&#xff0c;完美运行&#xff0c;有一万多字论文。 前台功能&#xff1a;用户的注册…
阅读更多...
社区论坛小程序系统源码+自定义设置+活动奖励 自带流量主 带完整的搭建教程

社区论坛小程序系统源码+自定义设置+活动奖励 自带流量主 带完整的搭建教程

大家好啊&#xff0c;又到了罗峰来给大家分享好用的源码的时间了。今天罗峰要给大家分享的是一款社区论坛小程序系统。社区论坛已经成为人们交流、学习、分享的重要平台。然而&#xff0c;传统的社区论坛往往功能单一、缺乏个性化设置&#xff0c;无法满足用户多样化的需求。而…
阅读更多...
Spring-Spring之AOP底层源码解析（下）

Spring-Spring之AOP底层源码解析（下）

ProxyFactory选择cglib或jdk动态代理原理 ProxyFactory在生成代理对象之前需要决定到底是使用JDK动态代理还是CGLIB技术&#xff1a; // config就是ProxyFactory对象// optimize为true,或proxyTargetClass为true,或用户没有给ProxyFactory对象添加interface if (config.isOpt…
阅读更多...
分类预测 | Matlab实现QPSO-SVM、PSO-SVM、SVM多特征分类预测对比

分类预测 | Matlab实现QPSO-SVM、PSO-SVM、SVM多特征分类预测对比

分类预测 | Matlab实现QPSO-SVM、PSO-SVM、SVM多特征分类预测对比 目录 分类预测 | Matlab实现QPSO-SVM、PSO-SVM、SVM多特征分类预测对比分类效果基本描述程序设计参考资料 分类效果 基本描述 1.Matlab实现QPSO-SVM、PSO-SVM、SVM分类预测对比&#xff0c;运行环境Matlab2018b…
阅读更多...
SpringBoot初始化

SpringBoot初始化

Springboot启动流程 框架初始化 配置资源加载器配置primarySources应用环境检测配置系统初始化器配置应用监听器配置main方法所在类 框架启动 自动化装配 初始化器解析 概览 类名: ApplicationContextInitializer介绍&#xff1a;Spring容器刷新之前执行的一个回调函数作用:…
阅读更多...
最新文章

Copyright @ 2022~2023