当前位置: 首页 > news >正文

深入了解Swagger注解:@ApiModel和@ApiModelProperty实用指南

在现代软件开发中,提供清晰全面的 API 文档 至关重要。@ApiModel@ApiModelProperty 这样的代码注解在此方面表现出色,通过增强模型及其属性的元数据来丰富文档内容。它们的主要功能是为这些元素命名和描述,使生成的 API 文档更加明确。

Swagger 注解 @ApiModel 和 @ApiModelProperty 的用法

@ApiModel@ApiModelProperty 的实际用例

这些注解不仅仅是为了展示;它们在各种情景中都发挥着实际的作用:

  • 文档生成:通过这些注解整合模型名称、描述和属性详情,可以简化准确详细的 API 文档编制工作。
  • 验证:利用 @ApiModelProperty 可以定义验证约束,如最大长度或最小值,帮助确保数据的完整性。
  • 模型解读:在生成的 API 指南中,@ApiModel@ApiModelProperty 提供的信息有助于明确展示模型,包括示例和详细描述。

注解应用指南

@ApiModel 的注解用法如下:

属性数据类型默认值说明
valueString""模型的名称
descriptionString""模型的描述
parentClass<?>Void.class模型的父类
discriminatorString""模型的鉴别器
subTypesClass<?>[]{}模型的子类
referenceString""模型的引用
exampleString""模型的示例

另一方面,@ApiModelProperty 的使用注解如下:

属性数据类型默认值说明
valueString""属性的名称
nameString""属性的名称
dataTypeString""属性的数据类型
requiredbooleanFALSE属性是否必需
exampleString""属性的示例
hiddenbooleanFALSE属性是否隐藏
allowableValuesString""属性的允许值范围
accessString""属性的访问权限
notesString""属性的注释
positionint0属性的位置

实践案例

考虑在一个用户管理系统中的用户模型,需要为其 API 提供清晰的定义。通过为我们的 User 类添加 @ApiModel 注解,以及用 @ApiModelProperty 描述每个属性,我们大大提高了文档的清晰度,使其对开发人员和用户更易于理解。

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
​
@ApiModel(value = "User", description = "用户模型")
public class User {@ApiModelProperty(value = "用户ID", example = "1")private Long id;@ApiModelProperty(value = "用户名", example = "john.doe")private String username;@ApiModelProperty(value = "年龄", example = "25")private Integer age;// 省略其他属性的getters和setters
​public Long getId() {return id;}
​public void setId(Long id) {this.id = id;}
​public String getUsername() {return username;}public void setUsername(String username) {this.username = username;}
​public Integer getAge() {return age;}
​public void setAge(Integer age) {this.age = age;}
}

这些注解确保了 API 文档有效地反映了模型及其属性,展示了名称、描述、类型和示例值。这种方法直接导致了一个界定清晰、易于使用的 API 参考资料。

关键注意事项

  • 集成相关的 Swagger 依赖并正确配置。
  • 注解必须准确定义属性,如名称、描述和数据类型。
  • 确保使用 @ApiModelProperty 的属性可以公开访问,并拥有适当的 getter 和 setter 方法。

关于注解使用的常见问题解答

问1:是否可以在一个模型上使用多个 @ApiModel 注解?

答1:不可以,一个模型应该有一个 @ApiModel 注解。

问2:一个属性上可以应用多个 @ApiModelProperty 注解吗?

答2:虽然一个属性可以有多个 @ApiModelProperty 注解,通常是为了提供不同的描述和设置。

与 Apifox 整合简化 API 管理

尽管 Swagger 很有用,但它使用起来可能比较麻烦,缺乏一些协作安全功能。因此,许多人转向使用 Apifox 的 IDEA 插件,以获得更强的功能和方便。它允许在 IDEA 中自动同步 Swagger 注解到 Apifox,并通过多端同步方便测试和维护。

Apifox 的 IDEA 插件

最后感谢每一个认真阅读我文章的人,礼尚往来总是要有的,虽然不是什么很值钱的东西,如果你用得到的话可以直接拿走:

这些资料,对于【软件测试】的朋友来说应该是最全面最完整的备战仓库,这个仓库也陪伴上万个测试工程师们走过最艰难的路程,希望也能帮助到你!

相关文章:

深入了解Swagger注解:@ApiModel和@ApiModelProperty实用指南

在现代软件开发中&#xff0c;提供清晰全面的 API 文档 至关重要。ApiModel 和 ApiModelProperty 这样的代码注解在此方面表现出色&#xff0c;通过增强模型及其属性的元数据来丰富文档内容。它们的主要功能是为这些元素命名和描述&#xff0c;使生成的 API 文档更加明确。 Api…...

Linux学习第48天:Linux USB驱动试验:保持热情,保持节奏,持续学习是作为一个技术人员应有的基本素质和要求

Linux版本号4.1.15 芯片I.MX6ULL 大叔学Linux 品人间百味 思文短情长 最近更新的速度和频率大不如以前&#xff0c;主要原因还是自己有些懈怠了。学习是一个持续努力的过程&#xff0c;一旦中断&#xff0c;再想保持以往的状态可能要…...

数据库索引简析

文章目录 前言一、索引是什么二、索引的有什么用三、索引的分类四、索引的数据结构总结 前言 在我们使用数据库的过程中&#xff0c;往往会碰到一个叫做索引的东西&#xff0c;不管是表的设计&#xff0c;还是数据库性能的优化往往都会涉及到索引。那么他是个什么东西&#xff…...

leetcode贪心(单调递增的数字、监控二叉树)

738.单调递增的数字 给定一个非负整数 N&#xff0c;找出小于或等于 N 的最大的整数&#xff0c;同时这个整数需要满足其各个位数上的数字是单调递增。 &#xff08;当且仅当每个相邻位数上的数字 x 和 y 满足 x < y 时&#xff0c;我们称这个整数是单调递增的。&#xff…...

如何在win7同样支持Webview2 在 WPF 中使用本地 Webview2 ,如何不依赖系统 Runtime

项目运行环境&#xff1a; .Net Framework 4.5.2 Windows 7 x64 Service Pack 1 WebView2 Microsoft.WebView2.FixedVersionRuntime.120.0.2210.91.x64 考虑到很多老项目&#xff0c;本项目使用的是.Net Framework 4.5.2&#xff0c;.Net 更高版本的其实也是可以支持的。 …...

【docker】网络模式管理

目录 一、Docker网络实现原理 二、Docker的网络模式 1、host模式 1.1 host模式原理 1.2 host模式实操 2、Container模式 2.2 container模式实操 3、none模式 4、bridger模式 4.1 bridge模式的原理 4.2 bridge实操 5、overlay模式 6、自定义网络模式 6.1 为什么需要…...

LiveGBS国标GB/T28181流媒体平台功能-国标级联中作为下级平台对接海康大华宇视华为政务公安内网等GB28181国标平台查看级联状态及会话

LiveGBS国标级联中作为下级平台对接海康大华宇视华为政务公安内网等GB28181国标平台查看级联状态及会话 1、GB/T28181级联是什么2、搭建GB28181国标流媒体平台3、获取上级平台接入信息3.1、如何提供信息给上级3.2、上级国标平台如何添加下级域3.2、接入LiveGBS示例 4、配置国标…...

技术发展驱动编程语言走向

未来编程语言的走向可能会受到多种因素的影响&#xff0c;包括技术进步、市场需求、开发人员的偏好和生态系统的演变等。以下是一些可能的发展趋势&#xff1a; 简洁性和易用性 随着技术的进步&#xff0c;编程语言可能会变得越来越简洁和易于使用。一些语言可能会引入更高级的…...

tp5+workman(GatewayWorker) 安装及使用

一、安装thinkphp5 1、宝塔删除php禁用函数putenv、pcntl_signal_dispatch、pcntl_wai、pcntl_signal、pcntl_alarm、pcntl_fork&#xff0c;执行安装命令。 composer create-project topthink/think5.0.* tp5 --prefer-dist 2、配置好站点之后&#xff0c;浏览器打开访问成…...

vscode安装Prettier插件,对vue3项目进行格式化

之前vscode因为安装了Vue Language Features (Volar)插件&#xff0c;导致Prettier格式化失效&#xff0c;今天有空&#xff0c;又重新设置了一下 1. 插件要先安装上 2. 打开settings.json {"editor.defaultFormatter": "esbenp.prettier-vscode","…...

macOS跨进程通信: XPC 创建实例

一&#xff1a;简介 XPC 是 macOS 里苹果官方比较推荐和安全的的进程间通信机制。 集成流程简单&#xff0c;但是比较绕。 主要需要集成 XPC Server 这个模块&#xff0c;这个模块最终会被 apple 的根进程 launchd 管理和以独立进程的方法唤起和关闭&#xff0c; 我们主app 进…...

Ubuntu18.04 升级Ubuntu20.04

文章目录 背景升级方法遇到的问题 背景 因项目环境需要&#xff0c;欲将Ubuntu18.04升级至Ubuntu20.04&#xff0c;参考网上其他小伙伴的方法&#xff0c;也遇到了一个问题&#xff0c;特此记录一下&#xff0c;希望能帮助其他有同样问题的小伙伴。 升级方法 参考&#xff1a…...

自动化测试怎么做?看完你就懂了。。。

前言 我想应该有很多测试人员应该有这样的疑虑&#xff0c;自动化测试要怎么去做&#xff0c;现在我把自己的一些学习经验分享给大家&#xff0c;希望对你们有帮助&#xff0c;有说的不好的地方&#xff0c;还请多多指教&#xff01; 对于测试人员来说&#xff0c;不管进行功…...

小秋SLAM入门实战opencv所有文章汇总

opencv_core和 opencv_imgcodecs是 OpenCV&#xff08;开源计算机视觉库&#xff09;的两个主要模块 【如何使用cv::erode()函数对图像进行腐蚀操作】 头文件用途 用OpenCV创建一张类型为CV_8UC1的单通道随机灰度图像 用OpenCV创建一张灰度黑色图像并设置某一列为白色 OpenCV创…...

2023年终总结(脚踏实地,仰望星空)

回忆录 2023年&#xff0c;经历非常多的大事情&#xff0c;找工作、实习、研究生毕业、堂哥结婚、大姐买车、申博、读博、参加马拉松&#xff0c;有幸这一年全家人平平安安&#xff0c;在稳步前进。算是折腾的一年&#xff0c;杭州、赣州、武汉、澳门、珠海、遵义来回跑。完成…...

Transforer逐模块讲解

本文将按照transformer的结构图依次对各个模块进行讲解&#xff1a; 可以看一下模型的大致结构&#xff1a;主要有encode和decode两大部分组成&#xff0c;数据经过词embedding以及位置embedding得到encode的时输入数据 输入部分 embedding就是从原始数据中提取出单词或位置&…...

macOS进程间通信的常用技术汇总

macOS进程间通信的常用技术汇总 命令行传参。yyds管道(pipe), 匿名管道&#xff0c; c的技术&#xff0c;可以跨平台使用 只能在父子进程间通信&#xff0c;由于是单向的管道&#xff0c;只能单方面传输数据。 如果需要双向传输&#xff0c;需要建立双向的两条管道才行 匿名管…...

高德地图信息窗体设置

1. 添加默认信息窗体 //构建信息窗体中显示的内容var info [];info.push(<div style"height: 36px; line-height: 45px; padding: 0px 20px; white-space:nowrap;">位置&#xff1a;北京</div>);info.push(<div style"height: 36px; line-heig…...

isEmpty 和 isBlank 的用法区别,居然一半的人答不上来.....

isEmpty 和 isBlank 的用法区别 isEmpty系列isBank系列 hi&#xff01;我是沁禹&#xff5e; 也许你两个都不知道,也许你除了isEmpty/isNotEmpty/isNotBlank/isBlank外,并不知道还有isAnyEmpty/isNoneEmpty/isAnyBlank/isNoneBlank的存在, come on ,让我们一起来探索org.apache…...

数据分析求职-简历准备

简历在整个求职过程中的重要性不言而喻&#xff0c;今天咱们来聊求职过程中简历准备的那些事儿~ 1. 简历究竟有啥用 求职的流程简单说就是&#xff1a;网申->笔试->面试->offer 其中网申环节&#xff0c;简历100%决定了你的通过与否&#xff0c;这个点大家都知道。…...

Xshell远程连接Kali(默认 | 私钥)Note版

前言:xshell远程连接&#xff0c;私钥连接和常规默认连接 任务一 开启ssh服务 service ssh status //查看ssh服务状态 service ssh start //开启ssh服务 update-rc.d ssh enable //开启自启动ssh服务 任务二 修改配置文件 vi /etc/ssh/ssh_config //第一…...

在HarmonyOS ArkTS ArkUI-X 5.0及以上版本中,手势开发全攻略:

在 HarmonyOS 应用开发中&#xff0c;手势交互是连接用户与设备的核心纽带。ArkTS 框架提供了丰富的手势处理能力&#xff0c;既支持点击、长按、拖拽等基础单一手势的精细控制&#xff0c;也能通过多种绑定策略解决父子组件的手势竞争问题。本文将结合官方开发文档&#xff0c…...

【项目实战】通过多模态+LangGraph实现PPT生成助手

PPT自动生成系统 基于LangGraph的PPT自动生成系统&#xff0c;可以将Markdown文档自动转换为PPT演示文稿。 功能特点 Markdown解析&#xff1a;自动解析Markdown文档结构PPT模板分析&#xff1a;分析PPT模板的布局和风格智能布局决策&#xff1a;匹配内容与合适的PPT布局自动…...

相机Camera日志分析之三十一:高通Camx HAL十种流程基础分析关键字汇总(后续持续更新中)

【关注我,后续持续新增专题博文,谢谢!!!】 上一篇我们讲了:有对最普通的场景进行各个日志注释讲解,但相机场景太多,日志差异也巨大。后面将展示各种场景下的日志。 通过notepad++打开场景下的日志,通过下列分类关键字搜索,即可清晰的分析不同场景的相机运行流程差异…...

今日科技热点速览

&#x1f525; 今日科技热点速览 &#x1f3ae; 任天堂Switch 2 正式发售 任天堂新一代游戏主机 Switch 2 今日正式上线发售&#xff0c;主打更强图形性能与沉浸式体验&#xff0c;支持多模态交互&#xff0c;受到全球玩家热捧 。 &#x1f916; 人工智能持续突破 DeepSeek-R1&…...

.Net Framework 4/C# 关键字(非常用,持续更新...)

一、is 关键字 is 关键字用于检查对象是否于给定类型兼容,如果兼容将返回 true,如果不兼容则返回 false,在进行类型转换前,可以先使用 is 关键字判断对象是否与指定类型兼容,如果兼容才进行转换,这样的转换是安全的。 例如有:首先创建一个字符串对象,然后将字符串对象隐…...

Python 包管理器 uv 介绍

Python 包管理器 uv 全面介绍 uv 是由 Astral&#xff08;热门工具 Ruff 的开发者&#xff09;推出的下一代高性能 Python 包管理器和构建工具&#xff0c;用 Rust 编写。它旨在解决传统工具&#xff08;如 pip、virtualenv、pip-tools&#xff09;的性能瓶颈&#xff0c;同时…...

[免费]微信小程序问卷调查系统(SpringBoot后端+Vue管理端)【论文+源码+SQL脚本】

大家好&#xff0c;我是java1234_小锋老师&#xff0c;看到一个不错的微信小程序问卷调查系统(SpringBoot后端Vue管理端)【论文源码SQL脚本】&#xff0c;分享下哈。 项目视频演示 【免费】微信小程序问卷调查系统(SpringBoot后端Vue管理端) Java毕业设计_哔哩哔哩_bilibili 项…...

适应性Java用于现代 API:REST、GraphQL 和事件驱动

在快速发展的软件开发领域&#xff0c;REST、GraphQL 和事件驱动架构等新的 API 标准对于构建可扩展、高效的系统至关重要。Java 在现代 API 方面以其在企业应用中的稳定性而闻名&#xff0c;不断适应这些现代范式的需求。随着不断发展的生态系统&#xff0c;Java 在现代 API 方…...

DiscuzX3.5发帖json api

参考文章&#xff1a;PHP实现独立Discuz站外发帖(直连操作数据库)_discuz 发帖api-CSDN博客 简单改造了一下&#xff0c;适配我自己的需求 有一个站点存在多个采集站&#xff0c;我想通过主站拿标题&#xff0c;采集站拿内容 使用到的sql如下 CREATE TABLE pre_forum_post_…...