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

目录

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

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


【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规范采用JSONYAML格式编写,并支持多种数据类型,可以描述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/

相关推荐
代码之光_198020 分钟前
保障性住房管理:SpringBoot技术优势分析
java·spring boot·后端
ajsbxi25 分钟前
苍穹外卖学习记录
java·笔记·后端·学习·nginx·spring·servlet
StayInLove44 分钟前
G1垃圾回收器日志详解
java·开发语言
对许1 小时前
SLF4J: Failed to load class “org.slf4j.impl.StaticLoggerBinder“
java·log4j
无尽的大道1 小时前
Java字符串深度解析:String的实现、常量池与性能优化
java·开发语言·性能优化
小鑫记得努力1 小时前
Java类和对象(下篇)
java
binishuaio1 小时前
Java 第11天 (git版本控制器基础用法)
java·开发语言·git
zz.YE1 小时前
【Java SE】StringBuffer
java·开发语言
老友@1 小时前
aspose如何获取PPT放映页“切换”的“持续时间”值
java·powerpoint·aspose
颜淡慕潇1 小时前
【K8S问题系列 |1 】Kubernetes 中 NodePort 类型的 Service 无法访问【已解决】
后端·云原生·容器·kubernetes·问题解决