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

无难事者若执2023-11-17 2:33

目录

个人主页: 【⭐️个人主页】

需要您的【💖 点赞+关注】支持 💯

【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迁移

SpringFox SpringDoc
@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

xml 复制代码 
<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
   <version>2.2.0</version>
</dependency>

Gradle

groovy 复制代码 
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

配置

application.yaml中增加springdoc的配置

yaml 复制代码 
# ======== 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配置

java 复制代码 
@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相关的接口权限放开访问权限

java 复制代码 
@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

xml 复制代码 
<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'

配置

yaml 复制代码 
# ======== 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/

相关推荐
Amor风信子3 分钟前
华为OD机试真题---战场索敌
java·开发语言·算法·华为od·华为
天天向上杰7 分钟前
简识JVM的栈帧优化共享技术
java·jvm
方圆想当图灵25 分钟前
缓存之美：万文详解 Caffeine 实现原理（下）
java·redis·缓存
栗豆包40 分钟前
w175基于springboot的图书管理系统的设计与实现
java·spring boot·后端·spring·tomcat
等一场春雨1 小时前
Java设计模式 十四 行为型模式 (Behavioral Patterns)
java·开发语言·设计模式
萧若岚2 小时前
Elixir语言的Web开发
开发语言·后端·golang
Channing Lewis2 小时前
flask实现重启后需要重新输入用户名而避免浏览器使用之前已经记录的用户名
后端·python·flask
Channing Lewis2 小时前
如何在 Flask 中实现用户认证？
后端·python·flask
酱学编程2 小时前
java中的单元测试的使用以及原理
java·单元测试·log4j
我的运维人生3 小时前
Java并发编程深度解析：从理论到实践
java·开发语言·python·运维开发·技术共享
热门推荐
01xgboost: Why not implement distributed XGBoost on top of spark02Dell服务器升级ubuntu 22.04失败解决03半导体应用系统一些小知识收集(strip&wafer mapping,EAP&scada)04密码学原理技术-第六章-introduction to pulibc-key cryptography05(欧拉)openEuler系统添加网卡文件配置流程、(欧拉)openEuler系统手动配置ipv6地址流程、(欧拉)openEuler系统网络管理说明06优化手机性能，解决卡顿问题：关闭这3个微信开关，释放内存空间07centos7 init.d 和system.d08Windows10安装PCL1.14.0及点云配准09渗透测试之SQLMAP工具详解 kali自带SQLmap解释 重点sqlmap --tamper 使用方式详解 搞完你就很nice了10ChatGPT + Stable Diffusion + 百度AI + MoviePy 实现文字生成视频，小说转视频，自媒体神器！(二)