在 Spring Boot 3.x 中使用 SpringDoc 2 / Swagger V3

SpringDoc V1 只支持到 Spring Boot 2.x

springdoc-openapi v1.7.0 is the latest Open Source release supporting Spring Boot 2.x and 1.x.

Spring Boot 3.x 要用 SpringDoc 2 / Swagger V3, 并且包名也改成了 springdoc-openapi-starter-webmvc-ui

SpringDoc V2 https://springdoc.org/v2/

配置

增加 Swagger 只需要在 pom.xml 中添加依赖

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

Spring Boot 启动时就会自动启用 Swagger, 从以下地址可以访问 接口形式(JSON, YAML)和WEB形式的接口文档

  • http://host:port/context-path/v3/api-docs
    • YAML格式 http://host:port/context-path/v3/api-docs.yaml
  • http://host:port/context-path/swagger-ui/index.html

如果要关闭, 启用, 自定义接口地址, 在 application.yml 中添加配置

springdoc:api-docs:path: /v3/api-docsenabled: false

对应WEB地址的配置为

springdoc:swagger-ui:path: /swagger-ui.htmlenabled: false

因为WEB界面的显示基于解析JSON接口返回的结果, 如果api-docs关闭, swagger-ui即使enable也无法使用

在开发和测试环境启动服务时, 可以用VM参数分别启用

# in VM arguments
-Dspringdoc.api-docs.enabled=true -Dspringdoc.swagger-ui.enabled=true

使用注解

@Tag

Swagger3 中可以用 @Tag 作为标签, 将接口方法进行分组. 一般定义在 Controller 上, 如果 Controller 没用 @Tag 注解, Swagger3 会用Controller的类名作为默认的Tag, 下面例子用 @Tag 定义了一个“Tutorial”标签, 带有说明"Tutorial management APIs", 将该标签应用于TutorialController后, 在 Swagger3 界面上看到的这个 Controller 下面的方法集合就是 Tutorial.

@Tag(name = "Tutorial", description = "Tutorial management APIs")
@RestController
@RequestMapping("/api")
public class TutorialController {//...
}

也可以将 @Tag 添加到单独的方法上, 这样在 Swagger3 界面上, 就会将这个方法跟同样是 Tutorial 标签的其它方法集合在一起.

public class AnotherController {@Tag(name = "Tutorial", description = "Tutorial APIs")@PostMapping("/tutorials")public ResponseEntity<Tutorial> createTutorial(@RequestBody Tutorial tutorial) {//...}
}

@Operation

Swagger3中 @Operation注解用于单个API方法. 例如

public class MoreController {@Operation(summary = "Retrieve a Tutorial by Id",description = "Some description",tags = { "tutorials", "get" })@GetMapping("/tutorials/{id}")public ResponseEntity<Tutorial> getTutorialById(@PathVariable("id") long id) {//...}
}

tags = { "tutorials", "get" }可以将一个方法放到多个Tag分组中

@ApiResponses 和 @ApiResponse

Swagger3 使用 @ApiResponses 注解标识结果类型列表, 用@ApiResponse注解描述各个类型. 例如

    public class AnotherController {@ApiResponses({@ApiResponse(responseCode = "200",content = { @Content(schema = @Schema(implementation = UserBO.class), mediaType = "application/json") }),@ApiResponse(responseCode = "404",description = "User not found.", content = { @Content(schema = @Schema()) })})@GetMapping("/user/{id}")public ResponseEntity<UserBO> getUserById(@PathVariable("id") long id) {return null;}
}

@Parameter

@Parameter注解用于描述方法参数, 例如:

@GetMapping("/tutorials")
public ResponseEntity<Map<String, Object>> getAllTutorials(@Parameter(description = "Search Tutorials by title") @RequestParam(required = false) String title,@Parameter(description = "Page number, starting from 0", required = true) @RequestParam(defaultValue = "0") int page,@Parameter(description = "Number of items per page", required = true) @RequestParam(defaultValue = "3") int size) {//...
}

@Schema annotation

Swagger3 用 @Schema 注解对象和字段, 以及接口中的参数类型, 例如

@Schema(description = "Tutorial Model Information")
public class Tutorial {@Schema(accessMode = Schema.AccessMode.READ_ONLY, description = "Tutorial Id", example = "123")private long id;@Schema(description = "Tutorial's title", example = "Swagger Tutorial")private String title;// getters and setters
}

accessMode = Schema.AccessMode.READ_ONLY用于在接口定义中标识字段只读

实例

定义接口

@Tag(name = "CRUD REST APIs for User Resource",description = "CRUD REST APIs - Create User, Update User, Get User, Get All Users, Delete User"
)
@Slf4j
@RestController
public class IndexController {@Operation(summary = "Get a user by its id")@GetMapping(value = "/user_get")public String doGetUser(@Parameter(name = "id", description = "id of user to be searched")@RequestParam(name = "id", required = true)String id) {return "doGetUser: " + id;}@Operation(summary = "Add a user")@PostMapping(value = "/user_add")public String doAddUser(@io.swagger.v3.oas.annotations.parameters.RequestBody(description = "User to add.", required = true)@RequestBody UserBO user) {return "doAddUser: " + user.getName();}@ApiResponses({@ApiResponse(responseCode = "200",content = { @Content(schema = @Schema(implementation = UserBO.class), mediaType = "application/json") }),@ApiResponse(responseCode = "404",description = "User not found.", content = { @Content(schema = @Schema()) })})@GetMapping("/user/{id}")public ResponseEntity<UserBO> getUserById(@PathVariable("id") long id) {return null;}
}

对于这行代码@io.swagger.v3.oas.annotations.parameters.RequestBody(description = "User to add.", required = true),
因为 Swagger3 的 RequestBody 类和 Spring MVC 的 RequestBody 重名了, 所以在注释中不得不用完整路径, 比较影响代码格式. 在GitHub上有对这个问题的讨论(链接 https://github.com/swagger-api/swagger-core/issues/3628), 暂时无解.

定义对象

@Schema(description = "UserBO Model Information")
@Data
public class UserBO {@Schema(description = "User ID")private String id;@Schema(description = "User Name")private String name;
}

参考

  • https://www.baeldung.com/spring-rest-openapi-documentation

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

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

相关文章

select,poll和epoll有什么区别

它们都是NIO中多路复用的三种实现机制&#xff0c;是由linux操作系统提供的。 用户空间和内核空间&#xff1a;操作系统为了保证系统安全&#xff0c;将内核分为两个部分&#xff0c;一个是用户空间&#xff0c;一个是内核空间。用户空间不能直接访问底层的硬件设备&#xff0…

IT廉连看——Uniapp——配置文件pages

IT廉连看——Uniapp——配置文件pages [IT廉连看] 本堂课主要为大家介绍pages.json这个配置文件 一、打开官网查看pages.json可以配置哪些属性。 下面边写边讲解 新建一个home页面理解一下这句话。 以下一些页面的通用配置 通用设置里我们可以对导航栏和状态栏进行一些设…

Android修行手册-集成Python开发环境

Unity3D特效百例案例项目实战源码Android-Unity实战问题汇总游戏脚本-辅助自动化Android控件全解手册再战Android系列Scratch编程案例软考全系列Unity3D学习专栏蓝桥系列ChatGPT和AIGC &#x1f449;关于作者 专注于Android/Unity和各种游戏开发技巧&#xff0c;以及各种资源分…

Debezium发布历史161

原文地址&#xff1a; https://debezium.io/blog/2023/09/13/debezium-2-4-beta2-released/ 欢迎关注留言&#xff0c;我是收集整理小能手&#xff0c;工具翻译&#xff0c;仅供参考&#xff0c;笔芯笔芯. Debezium 2.4.0.Beta2 Released September 13, 2023 by Chris Cranfo…

Apache Flink连载(三十五):Flink基于Kubernetes部署(5)-Kubernetes 集群搭建-1

🏡 个人主页:IT贫道-CSDN博客 🚩 私聊博主:私聊博主加WX好友,获取更多资料哦~ 🔔 博主个人B栈地址:豹哥教你学编程的个人空间-豹哥教你学编程个人主页-哔哩哔哩视频 目录 ​编辑

Python爬虫——Urllib库-2

编解码 问题引入 例如&#xff1a; https://www.baidu.com/s?wd章若楠 https://www.baidu.com/s?wd%E7%AB%A0%E8%8B%A5%E6%A5%A0 第二部分的一串乱码就是章若楠 如果这里是写的章若楠就会 产生这样的错误 所以我们就可以使用get请求方式的quote方法了 get请求方式的q…

laravel ApiResponse接口统一响应封装

一&#xff0c;新增接口返回码配置文件 在config中新增配置文件apicode.php <?phpreturn [ apicodes>[/*** Message("OK")* 对成功的 GET、PUT、PATCH 或 DELETE 操作进行响应。也可以被用在不创建新资源的 POST 操作上*/HTTP_OK > 200,/*** Message(&qu…

使用el-form之表单校验自动定位到报错位置问题,,提升用户体验

需求描述 由于需要填写的表单项太多&#xff0c;提交的时候校验不通过&#xff0c; 如果没填写的表单项在最上面&#xff0c;用户看不到不知道发生了啥&#xff0c; 所以需要将页面滚动定位到第一个报错的表单项位置&#xff0c;提升用户体验实现步骤 1. 给form表单添加ref …

数据中心GPU集群高性能组网技术分析

数据中心GPU集群组网技术是指将多个GPU设备连接在一起&#xff0c;形成一个高性能计算的集群系统。通过集群组网技术&#xff0c;可以实现多个GPU设备之间的协同计算&#xff0c;提供更大规模的计算能力&#xff0c;适用于需要大规模并行计算的应用场景。 常用的组网技术&…

1209. 带分数 刷题笔记

思路 暴力匹配 读入目标数 n 看n是否与ab/c相等 因为c里面的除法是整除 我们将 nab/c 转换为 c*na*cb 那么如何获得a,b&#xff0c;c 依题意 a&#xff0c;b&#xff0c;c三个数由1-9九个数字组成 且每个数字只能出现一次 由此 我们可以搜出123456789的全部排列方式…

我做的app上架应用市场一天,快破400下载量,0差评

上集说到&#xff0c;我做了一个叫QB音乐的安卓app&#xff0c;经过一段时间的自我使用与测试终于算发布了。我昨天顺便把它上架了奇妙应用市场&#xff0c;截止目前3月1号过去了一天&#xff0c;下载量快到400&#xff0c;0差评。看来还是能正常使用的。 一、为什么做这个ap…

CleanMyMac X2024免费Mac电脑清理和优化工具

CleanMyMac X是一款专业的 Mac 清理和优化工具&#xff0c;它具备一系列强大的功能&#xff0c;可以帮助用户轻松管理和维护他们的 Mac 电脑。以下是一些关于 CleanMyMac X 的主要功能和特点&#xff1a; 智能清理&#xff1a;CleanMyMac X 能够智能识别并清理 Mac 上的无用文件…

深入剖析k8s-Pod篇

为什么需要Pod&#xff1f; 进程是以进程组的方式组织在一起。受限制容器的“单进程模型”&#xff0c; 成组调用没有被妥善处理&#xff08;资源调用有限&#xff09;&#xff0c;使用资源囤积则导致复杂度上升。 在k8s项目中&#xff0c;Pod的实现需要使用一个中间容器——…

css【详解】—— 圣杯布局 vs 双飞翼布局 (含手写清除浮动 clearfix)

两者功能效果相同&#xff0c;实现方式不同 效果预览 两侧宽度固定&#xff0c;中间宽度自适应&#xff08;三栏布局&#xff09;中间部分优先渲染允许三列中的任意一列成为最高列 圣杯布局 通过左右栏填充容器的左右 padding 实现&#xff0c;更多细节详见注释。 <!DOCTYP…

《无线网络技术》考试版笔记

第一章 无线网络介绍 什么是多径效应&#xff0c;如何去克服&#xff1a; 在发射机和接收机之间没有明显的直线路径时&#xff0c;就会产生多径传播。如果两个信号彼此叠加&#xff0c;那么接收设备就无法正确解调信号&#xff0c;无法还原为它的原始数据形式。 可以稍微调整接…

【leetcode热题】求根到叶子节点数字之和

难度&#xff1a; 中等通过率&#xff1a; 40.6%题目链接&#xff1a;. - 力扣&#xff08;LeetCode&#xff09; 题目描述 给定一个二叉树&#xff0c;它的每个结点都存放一个 0-9 的数字&#xff0c;每条从根到叶子节点的路径都代表一个数字。 例如&#xff0c;从根到叶子…

Linux包管理dpkg、apt和snap

dpkg、apt和snap都是Ubuntu系统中用于软件管理的工具&#xff0c;但它们在功能和使用上有一些区别。 dpkg: dpkg是Debian包管理系统的底层工具&#xff0c;也是apt和其他高级包管理工具的基础。主要功能是用于安装、卸载、配置和构建Debian软件包&#xff08;.deb文件&#xff…

vue面试题:Computed 和 Watch 的区别?

Computed 和 Watch 的区别? 对于Computed&#xff1a;对于Watch&#xff1a;immediate&#xff1a;组件加载立即触发回调函数deep&#xff1a;深度监听&#xff0c;发现数据内部的变化&#xff0c;在复杂数据类型中使用&#xff0c;例如数组中的对象发生变化。需要注意的是&am…

USLE模型-LS因子的计算

目录 计算坡度计算填洼计算流向计算水流长度计算水平投影![在这里插入图片描述](https://img-blog.csdnimg.cn/direct/75e015b2d6874ce9b6652f2b8730b90f.png)计算可变的坡度指数m计算坡长因子L计算坡度因子S计算LS因子参考视频 计算坡度 准备好30米分辨率的dem 计算填洼 计…

速看!深夜悄悄分享一个电力优化代码集合包!

代码集合包如下&#xff1a; 主从博弈的智能小区定价策略及电动汽车调度策略 碳交易机制下的综合能源优化调度 两阶段鲁棒优化算法的微网多电源容量配置 冷热电多能互补综合能源系统优化调度 考虑预测不确定性的综合能源调度优化 考虑柔性负荷的综合能源系统低碳经济优化调度 考…