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

一、什么是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: alphagroup-configs:- group: bisdisplay-name: "业务接口文档"paths-to-match: '/**'packages-to-scan: org.shi9.module.bis- group: systemdisplay-name: "系统接口文档"paths-to-match: '/**'packages-to-scan: org.shi9.module.systemdefault-flat-param-object: true
knife4j:# 开启增强配置enable: true# 开启生产环境屏蔽（如果是生产环境，需要把下面配置设置true）
#  production: truesetting:language: zh_cnswagger-model-name: 实体类列表basic: # 开始授权认证enable: trueusername: adminpassword: 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 {@Beanpublic 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.rhkb.cn/news/247952.html

如若内容造成侵权/违法违规/事实不符，请联系长河编程网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

【Docker】数据持久化 挂载

【Docker】数据持久化 挂载

Docker的镜像是只读的&#xff0c;但是容器是可写的&#xff0c;我们可以将数据写入到容器&#xff0c;不过一旦容器删除数据将会丢 失&#xff0c;那么有什么办法能将数据进行持久化存储呢&#xff1f; ——在宿主机上开辟一块地方&#xff0c;存储内容和docker容器的存储内…
阅读更多...
基于Vue uniapp和java SpringBoot的汽车充电桩微信小程序

基于Vue uniapp和java SpringBoot的汽车充电桩微信小程序

摘要&#xff1a; 随着新能源汽车市场的迅猛发展&#xff0c;汽车充电桩的需求日益增长。为了满足市场需求&#xff0c;本课题开发了一款基于Java SpringBoot后端框架和Vue uniapp前端框架的汽车充电桩微信小程序。该小程序旨在为用户提供一个简洁高效的充电服务平台&#xff0…
阅读更多...
Vite+Electron快速构建一个VUE3桌面应用（一）

Vite+Electron快速构建一个VUE3桌面应用（一）

一. 简介 首先&#xff0c;介绍下vite和Electron。 Vite是一种新型前端构建工具&#xff0c;能够显著提升前端开发体验。Electron是一个使用 JavaScript、HTML 和 CSS 构建桌面应用程序的框架。 嵌入Chromium和Node.js到二进制的 Electron 允许您保持一个 JavaScript 代码代码…
阅读更多...
git仓库批量备份

git仓库批量备份

git的mirror参数 在git中&#xff0c;--mirror是一个用于克隆和推送操作的参数。它用于创建一个镜像仓库&#xff0c;包含了源仓库的所有分支、标签和提交历史记录。 当使用git clone --mirror <source-repo>命令时&#xff0c;会创建一个完全相同的镜像仓库&#xff0…
阅读更多...
ROS学习笔记11——ROS中的重名问题

ROS学习笔记11——ROS中的重名问题

一、ros功能包重名——ros工作空间覆盖 功能包重名时&#xff0c;会按照 ROS_PACKAGE_PATH 查找&#xff0c;在前的会优先执行。ROS 会解析 .bashrc 文件&#xff0c;并生成 ROS_PACKAGE_PATH ROS包路径&#xff0c;即调用功能包的顺序&#xff0c;该变量中按照 .bashrc 中配置…
阅读更多...
《安富莱嵌入式周报》第331期：单片机实现全功能软件无线电，开源电源EEZ升级主控，ARM 汇编用户指南，UDS统一诊断服务解析，半导体可靠性设计手册

《安富莱嵌入式周报》第331期：单片机实现全功能软件无线电，开源电源EEZ升级主控，ARM 汇编用户指南，UDS统一诊断服务解析，半导体可靠性设计手册

周报汇总地址&#xff1a;嵌入式周报 - uCOS & uCGUI & emWin & embOS & TouchGFX & ThreadX - 硬汉嵌入式论坛 - Powered by Discuz! 目录&#xff1a; 1、单片机实现低配版全功能软件无线电&#xff0c;范围0.5-30 MHz&#xff0c;支持SSB、AM、FM和CW …
阅读更多...
websocket 通信协议

websocket 通信协议

websocket是什么 答: 它是一种网络通信协议&#xff0c;是 HTML5 开始提供的一种在单个 TCP 连接上进行全双工通讯的协议。 意思就是服务器可以主动向客户端推送信息&#xff0c;客户端也可以主动向服务器发送信息 属于服务器推送技术的一种. 为什么需要websocket? 疑问?…
阅读更多...
python爬虫demo——爬取历史平均房价

python爬虫demo——爬取历史平均房价

简单爬取历史房价 需求 爬取的网站汇聚数据的城市房价 https://fangjia.gotohui.com/ 功能 选择城市 https://fangjia.gotohui.com/fjdata-3 需要爬取年份的数据&#xff0c;等等 https://fangjia.gotohui.com/years/3/2018/ 使用bs4模块 使用bs4模块快速定义需要爬取的…
阅读更多...
安装mmcv-full（包括安装torch以及mmcv的离线安装方式）

安装mmcv-full（包括安装torch以及mmcv的离线安装方式）

文章目录 1. 安装torchtorch的下载链接 安装mmcv-fullmmcv-full的下载链接 在安装mmcv-full中通常需要安装torchmmcv-full。 1. 安装torch 在安装torch的时候&#xff0c;可以根据自身电脑是否有显卡&#xff0c;可以选择安装CPU版本还是GPU版本。mmcv-full也是同理。 安装to…
阅读更多...
shell - 正则表达式和grep命令和sed命令

shell - 正则表达式和grep命令和sed命令

一.正则表达式概述 1.正则表达式定义 1.1 定义 使用字符串描述、匹配一系列符合某个规则的字符串 1.2 了解 普通字符&#xff1a; 大小写字母、数字、标点符号及一些其它符号元字符&#xff1a; 在正则表达式中具有特殊意义的专用字符 1.3 层次分类 基础正则表达式扩展正…
阅读更多...
编写交互式 Shell 脚本

编写交互式 Shell 脚本

在日常的系统管理和自动化任务中&#xff0c;使用 Shell 脚本可以为我们节省大量时间和精力。 文章将以输入 IP 为例&#xff0c;通过几个版本逐步完善一个案例。 原始需求 编写一个交互式的 Shell 脚本&#xff0c;运行时让用户可以输入IP地址&#xff0c;并且脚本会将输入…
阅读更多...
css 中 flex 布局最后一行实现左对齐

css 中 flex 布局最后一行实现左对齐

问题 flex 布局最后一行没有进行左对齐显示&#xff1a; <div classparent><div classchild></div><div classchild></div><div classchild></div><div classchild></div><div classchild></div><div…
阅读更多...
Git初识

Git初识

&#x1f4d9; 作者简介 &#xff1a;RO-BERRY &#x1f4d7; 学习方向&#xff1a;致力于C、C、数据结构、TCP/IP、数据库等等一系列知识 &#x1f4d2; 日后方向 : 偏向于CPP开发以及大数据方向&#xff0c;欢迎各位关注&#xff0c;谢谢各位的支持 在学习Git之前我们先引入一…
阅读更多...
异步任务的一些思考

异步任务的一些思考

前言 XXL-Job部署教程 项目中&#xff0c;必然少不了数据的导入导出&#xff0c;针对数据的导入导出简单复盘一下。 为了不占用资源消耗时间&#xff0c;影响用户体验&#xff0c;大量数据的导入导出一般都是异步执行 导入的时候&#xff0c;如果数据量很大&#xff0c;一次…
阅读更多...
推荐一款Linux、数据库、Redis、MongoDB统一管理平台！

推荐一款Linux、数据库、Redis、MongoDB统一管理平台！

官方演示 状态查看 ssh 终端 文件操作 数据库操作 sql 编辑器 在线增删改查数据 Redis 操作 Mongo 操作 系统管理 账号管理 角色管理 资源管理 一.安装 1.下载安装包 cd /opt wget https://gitee.com/dromara/mayfly-go/releases/download/v1.7.1/mayfly-go-linux-amd64.zi…
阅读更多...
StoryGPT-V——可以生成漫画故事的多模态大模型

StoryGPT-V——可以生成漫画故事的多模态大模型

前言 目前&#xff0c;大型模型在复杂故事可视化任务方面依然面临着重大挑战。这是因为此类任务需要对框架描述中的代词&#xff08;例如He、她、他们、他们&#xff09;进行解析&#xff0c;即在分辨率和确保跨帧的角色和背景融合方面进行详细解剖。尽管存在这些挑战&#xf…
阅读更多...
12.1 关键点提取------Harris原理及代码

12.1 关键点提取------Harris原理及代码

一、原理 该原理看了Harris角点检测原理详解-CSDN博客的博文&#xff0c;在这里写一遍是作为笔记&#xff0c;以供后参考。 1.什么是角点 角点就是图片中的一些突变的点&#xff0c;如下图所示。图中的点都是菱角分明的一些凸出来或凹进去的点。 我们可以直观的概括下角点所具…
阅读更多...
广东盈致mes系统在注塑行业的应用

广东盈致mes系统在注塑行业的应用

广东盈致MES系统在注塑行业的应用主要体现在以下几个方面&#xff1a; 生产计划与调度&#xff1a;盈致MES系统能够根据订单需求和生产计划&#xff0c;自动生成生产任务&#xff0c;并跟踪生产进度&#xff0c;确保按时完成生产任务。通过与注塑机的集成&#xff0c;系统可以自…
阅读更多...
Jupyter notebook文件默认存储路径以及更改方法

Jupyter notebook文件默认存储路径以及更改方法

目录 1、文件默认存储路径怎么查&#xff1f;2、文件默认存储路径怎么改&#xff1f; 转自&#xff1a;https://blog.csdn.net/fengyeer20120/article/details/109483362 初次使用Jupyter Notebook&#xff0c;确实好用啊&#xff01;但安装Anaconda后&#xff0c;打开Jupyter …
阅读更多...
【Pg数据库】删除数据库失败，提示有session正在连接

【Pg数据库】删除数据库失败，提示有session正在连接

目录 问题现象原因分析处理方法1.断开所有连接2. 查找相关连接数据库的主机信息3. 再次删除 总结 问题现象 Navicat 删除 PostgreSQL 数据库时失败&#xff0c;提示&#xff1a;正在被其他用户访问&#xff08;有session正在连接&#xff09;如何处理&#xff1f; 如下所示&am…
阅读更多...
最新文章
推荐文章

Copyright @ 2022~2023

友情链接： 我的编程经验分享 一条长河网 尧图网站开发