【SpringBoot3】集成Knife4j、springdoc-openapi作为接口文档

news2024/11/16 23:33:27

一、什么是springdoc-openapi

Springdoc-openapi 是一个用于生成 OpenAPI（之前称为 Swagger）文档的库，专为 Spring Boot 应用程序设计。它可以根据你的 Spring MVC 控制器、REST 控制器和其他 Spring Bean 自动生成 OpenAPI 文档，从而帮助你在开发 RESTful API 时更加高效地管理和维护 API 文档。Springdoc-openapi 支持 OpenAPI 3.x 版本，并提供了一些额外的功能，如自定义配置、注解支持和与 Spring Boot 的无缝集成。

当你构建 RESTful API 时，API 文档是非常重要的，因为它们提供了对 API 的清晰描述，包括可用端点、请求参数、响应模型等信息。Springdoc-openapi 就是为了简化生成这些 API 文档而设计的。

Springdoc-openapi 的主要功能包括：

  1. 自动生成文档： Springdoc-openapi 可以自动扫描你的 Spring Boot 应用程序，并根据其中的控制器和其他相关组件生成 OpenAPI 文档。你无需手动编写文档，大部分信息都是自动生成的。

  2. 支持 OpenAPI 3.x： Springdoc-openapi 支持 OpenAPI 3.x 版本规范，这是当前 RESTful API 开发的主流规范。

  3. 注解支持： 它与 Spring MVC 注解和其他常见的 Spring 注解完全兼容，你可以使用这些注解来定制 API 的文档信息，例如请求参数的描述、响应的格式等。

  4. 自定义配置： Springdoc-openapi 提供了丰富的配置选项，你可以根据项目的需求进行自定义配置，以满足特定的文档生成需求。

  5. 集成简便： 由于 Springdoc-openapi 是专为 Spring Boot 应用程序设计的，因此它与 Spring Boot 无缝集成。你只需将 Springdoc-openapi 添加到项目的依赖中，它就会自动集成到你的应用程序中，开始生成 API 文档。

springdoc-openapi 使得生成和维护 RESTful API 文档变得简单而高效，帮助开发人员专注于业务逻辑而不是文档的编写。

在这里插入图片描述

核心注解

以下是 Springdoc-openapi 中一些常用的核心注解及其描述：

注解描述
@OpenAPIDefinition定义 OpenAPI 规范的基本信息，如 API 的标题、版本、服务器等
@Operation用于描述 API 操作（端点），包括操作的摘要、描述、请求和响应等信息
@ApiResponse定义操作的响应，包括响应的状态码、描述和响应模型等信息
@Parameter定义操作的参数，包括路径参数、查询参数、请求头参数等
@PathVariable定义路径参数，用于提取 URL 中的变量
@RequestParam定义查询参数，用于从请求中获取参数的值
@ApiParam在方法参数上使用，用于描述参数的含义和约束
@ApiResponses在控制器类上使用，为多个操作定义通用的响应规范
@ApiResponseExtension在 @Operation 或 @ApiResponse 上使用，用于扩展响应信息
@SecurityRequirement定义操作所需的安全要求，如需要的身份验证方案、安全范围等
@SecurityScheme定义安全方案，包括认证方式（如 Basic、OAuth2 等）、令牌 URL、授权 URL 等
@Tags定义操作的标签，用于对操作进行分类和组织
@Hidden在文档中隐藏标记的操作或参数，可以用于隐藏一些内部或不需要在文档中展示的部分
@Extension用于为生成的 OpenAPI 文档添加自定义的扩展信息，可以在文档中增加额外的元数据或自定义字段
@RequestBodySchema定义请求体的数据模型，允许对请求体进行更细粒度的描述和约束，如属性的名称、类型、格式、必填性等
@ApiResponseSchema定义响应的数据模型，允许对响应体进行更细粒度的描述和约束，如属性的名称、类型、格式、必填性等
@ExtensionProperty在 @Extension 注解上使用，用于定义自定义扩展的属性，可以添加额外的元数据或自定义字段到生成的 OpenAPI 文档中

这些注解可以帮助开发者更精细地描述 API 的各个方面，从而生成更加详细和准确的 OpenAPI 文档。

从 Swagger 2 升级为 Swagger 3

下面是将 Swagger 2 注解替换为 Swagger 3 注解的翻译：

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

这些转换可以帮助将现有的 Swagger 2 注解替换为 Swagger 3 注解，以便与 Springdoc-openapi-starter-webmvc-ui 库一起使用。

二、什么是Knife4j

Knife4j 是一个基于 Swagger 实现的接口文档管理工具，它提供了一套简单易用的 UI 界面，用于展示和管理 Swagger 生成的 API 文档。与传统的 Swagger UI 相比，Knife4j 在 UI 设计和功能上进行了改进和增强，使得接口文档的浏览和管理更加方便和直观。

Knife4j 的特点和功能包括：

  1. 美观的界面设计： Knife4j 提供了一个美观、直观的界面，用户可以通过该界面轻松地浏览和理解 API 文档，以及进行相关操作。

  2. 增强的交互功能： Knife4j 在 Swagger UI 的基础上增加了一些交互功能，如请求参数的快速填充、响应结果的格式化显示等，提升了用户体验。

  3. 便捷的文档导航： Knife4j 提供了便捷的文档导航功能，用户可以通过目录结构快速定位到所需的接口文档，方便查阅和使用。

  4. 支持在线调试： Knife4j 允许用户在界面上直接进行接口调用和测试，无需额外的工具或插件，便可完成接口的调试和验证。

  5. 自动生成文档： Knife4j 可以直接集成到 Spring Boot 项目中，通过注解和配置自动生成接口文档，简化了文档编写的工作量。

总的来说，Knife4j 是一个功能强大、易用的接口文档管理工具，能够帮助开发者更加高效地管理和维护 API 文档，提升接口开发和调试的效率。

主要配置项

在以前的版本中,开发者需要在配置文件中手动使用@EnableKnife4j来使用增强，自2.0.6版本后,只需要在配置文件中配置knife4j.enable=true即可不在使用注解

注意：要使用Knife4j提供的增强，knife4j.enable=true必须开启

各个配置属性说明如下：

属性默认值说明值
knife4j.enablefalse是否开启Knife4j增强模式
knife4j.corsfalse是否开启一个默认的跨域配置,该功能配合自定义Host使用
knife4j.productionfalse是否开启生产环境保护策略
knife4j.basic对Knife4j提供的资源提供BasicHttp校验,保护文档
knife4j.basic.enablefalse关闭BasicHttp功能
knife4j.basic.usernamebasic用户名
knife4j.basic.passwordbasic密码
knife4j.documents自定义文档集合，该属性是数组
knife4j.documents.group所属分组
knife4j.documents.name类似于接口中的tag,对于自定义文档的分组
knife4j.documents.locationsmarkdown文件路径,可以是一个文件夹(classpath:markdowns/*)，也可以是单个文件(classpath:md/sign.md)
knife4j.setting前端Ui的个性化配置属性
knife4j.setting.enable-after-scripttrue调试Tab是否显示AfterScript功能,默认开启
knife4j.setting.languagezh-CNUi默认显示语言,目前主要有两种:中文(zh-CN)、英文(en-US)
knife4j.setting.enable-swagger-modelstrue是否显示界面中SwaggerModel功能
knife4j.setting.swagger-model-nameSwagger Models重命名SwaggerModel名称,默认
knife4j.setting.enable-document-managetrue是否显示界面中"文档管理"功能
knife4j.setting.enable-reload-cache-parameterfalse是否在每个Debug调试栏后显示刷新变量按钮,默认不显示
knife4j.setting.enable-versionfalse是否开启界面中对某接口的版本控制,如果开启，后端变化后Ui界面会存在小蓝点
knife4j.setting.enable-request-cachetrue是否开启请求参数缓存
knife4j.setting.enable-filter-multipart-apisfalse针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,如果开启此配置,默认展示一个Post类型的接口地址
knife4j.setting.enable-filter-multipart-api-method-typePOST具体接口的过滤类型
knife4j.setting.enable-hostfalse是否启用Host
knife4j.setting.enable-host-textfalseHOST地址
knife4j.setting.enable-home-customfalse是否开启自定义主页内容
knife4j.setting.home-custom-path主页内容Markdown文件路径
knife4j.setting.enable-searchfalse是否禁用Ui界面中的搜索框
knife4j.setting.enable-footertrue是否显示Footer
knife4j.setting.enable-footer-customfalse是否开启自定义Footer
knife4j.setting.footer-custom-contentfalse自定义Footer内容
knife4j.setting.enable-dynamic-parameterfalse是否开启动态参数调试功能
knife4j.setting.enable-debugtrue启用调试
knife4j.setting.enable-open-apitrue显示OpenAPI规范
knife4j.setting.enable-grouptrue显示服务分组

三、SpringBoot3.0 集成 Knife4j 步骤

1、添加依赖（3.0和2.0不一样）

<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
	<version>4.4.0</version>
</dependency>
  • Spring Boot 3 只支持OpenAPI3规范
  • Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突
  • JDK版本必须 >= 17

2、在 application.yml 中添加配置

springdoc:
  swagger-ui:
    tags-sorter: alpha
  group-configs:
    - group: bis
      display-name: "业务接口文档"
      paths-to-match: '/**'
      packages-to-scan: org.shi9.module.bis
    - group: system
      display-name: "系统接口文档"
      paths-to-match: '/**'
      packages-to-scan: org.shi9.module.system
  default-flat-param-object: true
knife4j:
  # 开启增强配置
  enable: true
  # 开启生产环境屏蔽（如果是生产环境，需要把下面配置设置true）
#  production: true
  setting:
    language: zh_cn
    swagger-model-name: 实体类列表
  basic: # 开始授权认证
    enable: true
    username: admin
    password: 123456

在 group-configs 下面配置不同的模块的接口分组，也可以通过代码配置，建议在yml中配置。代码配置类似如下：

@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("springshop-public")
            .pathsToMatch("/public/**")
            .build();
}
@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
            .group("springshop-admin")
            .pathsToMatch("/admin/**")
            .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
            .build();
}

3、增加配置类 SwaggerConfig.java

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.shi9.common.constant.CommonConstant;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        Contact contact = new Contact();
        contact.setEmail("wlddhj@163.com");
        contact.setName("huangjian");
        contact.setUrl("http://doc.xiaominfo.com");
        return new OpenAPI()
                // 增加swagger授权请求头配置
                .components(new Components().addSecuritySchemes(CommonConstant.X_ACCESS_TOKEN,
                        new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme(CommonConstant.X_ACCESS_TOKEN)))
                .info(new Info()
                        .title("Shi9 后台服务API接口文档")
                        .version("1.0")
                        .contact(contact)
                        .description("Knife4j集成springdoc-openapi示例")
                        .termsOfService("http://doc.xiaominfo.com")
                        .license(new License().name("Apache 2.0")
                                .url("http://www.apache.org/licenses/LICENSE-2.0.html")));
    }
}

4、启动项目

项目启动后，直接打开地址 http://localhost:8081/doc.html，可以看见类型如下页面

在这里插入图片描述

参考

  • https://doc.xiaominfo.com/docs/quick-start
  • https://springdoc.org/#getting-started
  • https://springdoc.org/
  • https://gitee.com/xiaoym/knife4j

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

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈，一经查实，立即删除！

相关文章

如何使用手机安装JuiceSSH远程连接本地Linux服务器

如何使用手机安装JuiceSSH远程连接本地Linux服务器

⛳️ 推荐 前些天发现了一个巨牛的人工智能学习网站&#xff0c;通俗易懂&#xff0c;风趣幽默&#xff0c;忍不住分享一下给大家。点击跳转到网站。 文章目录 ⛳️ 推荐1. Linux安装cpolar2. 创建公网SSH连接地址3. JuiceSSH公网远程连接4. 固定连接SSH公网地址5. SSH固定地址…
阅读更多...
如何分辨芯片是原装 or 散新？

如何分辨芯片是原装 or 散新？

随着时代发展&#xff0c;集成电路产品层出不穷&#xff0c;很多无良厂商为降低成本&#xff0c;增大利润&#xff0c;回收芯片打磨成散新芯片出售&#xff0c;因此电子工程师必须分辨采购的芯片是否原装&#xff0c;下面将谈谈芯片的分辨方法&#xff0c;希望对小伙伴们有所帮…
阅读更多...
电商API接口平台：让数据成为生产力！

电商API接口平台：让数据成为生产力！

随着数字化商业时代的到来&#xff0c;API接口已成为电商资源连接利器&#xff0c;也是全球传统互联网企业转型的基础。 2021年 Google Cloud 研究显示&#xff0c;全球互联网企业近3/4的企业持续投入数字化转型&#xff0c;2/3的企业在持续增加投入&#xff0c;从这组数据可以…
阅读更多...
Mysql 更新数据

Mysql 更新数据

MySQL中使用UPDATE语句更新表中的记录&#xff0c;可以更新特定的行或者同时更新所有的行。基本语法结构如下&#xff1a; UPDATE table_name SET column_name1 value1,column_name2 value2,……, column_namen valuen WHERE(condition); column_name1,column_name2,……,…
阅读更多...
服装行业ERP系统解决方案

服装行业ERP系统解决方案

我国的服装企业大多属于劳动密集型&#xff0c;主要有三种类型&#xff1a;自有品牌服装生产销售企业、接订单生产型企业及处于产业链下游的零售分销企业。在经营过程中&#xff0c;服装行业面临诸多挑战&#xff0c;如流行周期短、季节性强&#xff0c;市场变化快&#xff1b;…
阅读更多...
隧道高清广播技术优势与应用

隧道高清广播技术优势与应用

1、传统隧道广播 存在回音大听不清楚的问题 隧道有线广播作为隧道机电系统的重要组成部分&#xff0c;在隧道发生紧急情况时&#xff0c;是工作人员发布语音信息组织救援、疏导车辆与人员撤离、紧急调度的有力手段&#xff0c;隧道广播的清晰度直接影响隧道内司乘人员获取…
阅读更多...
ElasticSearch 8.x 使用 snapshot（快照）进行数据迁移

ElasticSearch 8.x 使用 snapshot（快照）进行数据迁移

ElasticSearch 1、ElasticSearch学习随笔之基础介绍 2、ElasticSearch学习随笔之简单操作 3、ElasticSearch学习随笔之java api 操作 4、ElasticSearch学习随笔之SpringBoot Starter 操作 5、ElasticSearch学习随笔之嵌套操作 6、ElasticSearch学习随笔之分词算法 7、ElasticS…
阅读更多...
基于Java SSM框架实现影院购票系统项目【项目源码+论文说明】计算机毕业设计

基于Java SSM框架实现影院购票系统项目【项目源码+论文说明】计算机毕业设计

基于java的SSM框架实现影院购票系统演示 摘要 21世纪的今天&#xff0c;随着社会的不断发展与进步&#xff0c;人们对于信息科学化的认识&#xff0c;已由低层次向高层次发展&#xff0c;由原来的感性认识向理性认识提高&#xff0c;管理工作的重要性已逐渐被人们所认识&#…
阅读更多...
MySQL进阶45讲【8】MySQL事务到底是隔离的还是不隔离的？

MySQL进阶45讲【8】MySQL事务到底是隔离的还是不隔离的？

1 前言 在 MySQL进阶45讲【3】事务隔离的恩恩怨怨 这篇文章和大家讲事务隔离级别的时候提到过&#xff0c;如果是可重复读隔离级别&#xff0c;事务T启动的时候会创建一个视图read-view&#xff0c;之后事务T执行期间&#xff0c;即使有其他事务修改了数据&#xff0c;事务T看…
阅读更多...
can中继方案

can中继方案

为了实现灵活的网络拓扑&#xff0c;不受主干线和直线的长度限制以及终端电阻的位置限制。产生了can中继的需求。 安森美的AMIS-42600-D芯片可以实现can总线扩展、CAN总线中继等需求。AMIS-42700 A
阅读更多...
吉利汽车：S-SDLC融入开发体系，推动智能汽车安全发展

吉利汽车：S-SDLC融入开发体系，推动智能汽车安全发展

吉利汽车是中国汽车行业的知名品牌&#xff0c;是一家具有国际化视野的汽车企业&#xff0c;在中国汽车市场自主品牌中占据领军地位。吉利汽车集团数字化中心利用数字化技术优势赋能业务升级&#xff0c;推动研发效率提升和产品安全能力拓展&#xff0c;进行整体数字化转型。 在…
阅读更多...
PyTorch2ONNX-分类模型：速度比较（固定维度、动态维度）、精度比较

PyTorch2ONNX-分类模型：速度比较（固定维度、动态维度）、精度比较

图像分类模型部署: PyTorch -> ONNX 1. 模型部署介绍 1.1 人工智能开发部署全流程 #mermaid-svg-bAJun9u4XeSykIbg {font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}#mermaid-svg-bAJun9u4XeSykIbg .error-icon{fill:#552222;}…
阅读更多...
5G安卓核心板开发板_MT6833天玑700规格参数

5G安卓核心板开发板_MT6833天玑700规格参数

核心板采用沉金生产工艺&#xff0c;耐腐蚀抗干扰&#xff0c;支持-20℃-70℃环境下7x24小时稳定运行&#xff0c;尺寸仅为45mmx48mm x2.65mm&#xff0c;可嵌入到各种智能产品中&#xff0c;助力智能产品便携化及功能差异化。 联发科MT6833处理器采用台积电 7nm 制程的5G SoC…
阅读更多...
基于YOLOv8深度学习的水稻叶片病害智能诊断系统【python源码+Pyqt5界面+数据集+训练代码】深度学习实战

基于YOLOv8深度学习的水稻叶片病害智能诊断系统【python源码+Pyqt5界面+数据集+训练代码】深度学习实战

《博主简介》 小伙伴们好&#xff0c;我是阿旭。专注于人工智能、AIGC、python、计算机视觉相关分享研究。 ✌更多学习资源&#xff0c;可关注公-仲-hao:【阿旭算法与机器学习】&#xff0c;共同学习交流~ &#x1f44d;感谢小伙伴们点赞、关注&#xff01; 《------往期经典推…
阅读更多...
USB-C显示器：未来显示技术的革新者

USB-C显示器：未来显示技术的革新者

随着科技的不断发展&#xff0c;显示技术也在不断进步&#xff0c;而USB-C显示器作为最新的显示技术&#xff0c;正在引领着显示行业的发展潮流。USB-C显示器具有许多优点&#xff0c;如高速传输、便捷连接、节能环保等&#xff0c;使其成为未来显示技术的革新者。 一、USB-C显…
阅读更多...
[Grafana]ES数据源Alert告警发送

[Grafana]ES数据源Alert告警发送

简单的记录一下使用es作为数据源&#xff0c;如何在发送告警是带上相关字段 目录 前言 一、邮件配置 二、配置 1.Query 2.Alerts 总结 前言 ES作为数据源&#xff0c;算是Grafana中比较常见的&#xff0c;Alerts告警是我近期刚接触&#xff0c;有一个需求是当表空间大于…
阅读更多...
Apache SeaTunnel (不含web) Window11 本机搭建（非源码）

Apache SeaTunnel (不含web) Window11 本机搭建（非源码）

启动环境 需要提前准备的(只提供作者试过且可行的方案) window11ubuntu20(wsl2) window11内置ubuntu的方式自行百度&#xff0c;此处不做陈述jdk8mysql8navicatvscode 环境准备不做过多陈述&#xff0c;以下是正式的安装启动步骤 SeaTunnel 2.3.3 资源准备 第一步: 创建文件…
阅读更多...
基于Javaweb开发的二手图书零售系统详细设计【附源码】

基于Javaweb开发的二手图书零售系统详细设计【附源码】

基于Javaweb开发的二手图书零售系统详细设计【附源码】 &#x1f345; 作者主页 央顺技术团队 &#x1f345; 欢迎点赞 &#x1f44d; 收藏 ⭐留言 &#x1f4dd; &#x1f345; 文末获取源码联系方式 &#x1f4dd; &#x1f345; 查看下方微信号获取联系方式 承接各种定制系统…
阅读更多...
【webrtc】‘ninja.exe‘ 不是内部或外部命令，也不是可运行的程序及vs2019 重新构建m98

【webrtc】‘ninja.exe‘ 不是内部或外部命令，也不是可运行的程序及vs2019 重新构建m98

werbtc 就是用ninja.exe 来构建找到了自己以前构建的webrtc 原版 m98 【m98 】webrtc ninja 构建 、example、tests 及OWT- P2P 项目P2PMFC-E2E-m98G:\CDN\rtcCli\webrtc-checkout\src找到了自己的deptools的路径 deptools里确实没有ninja.exe D:\SOFT\depot_tools\third_party…
阅读更多...
Nginx进阶篇【五】

Nginx进阶篇【五】

Nginx进阶篇【五】 八、Nginx实现服务器端集群搭建8.1.Nginx与Tomcat部署8.1.1.环境准备(Tomcat)8.1.1.1.浏览器访问:8.1.1.2.获取动态资源的链接地址:8.1.1.3.在Centos上准备一个Tomcat作为后台web服务器8.1.1.4.准备一个web项目&#xff0c;将其打包为war8.1.1.5.启动tomcat进…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023