深入了解Swagger注解:@ApiModel和@ApiModelProperty实用指南
在现代软件开发中,提供清晰全面的 API 文档 至关重要。@ApiModel
和 @ApiModelProperty
这样的代码注解在此方面表现出色,通过增强模型及其属性的元数据来丰富文档内容。它们的主要功能是为这些元素命名和描述,使生成的 API 文档更加明确。
@ApiModel
和 @ApiModelProperty
的实际用例
这些注解不仅仅是为了展示;它们在各种情景中都发挥着实际的作用:
- 文档生成:通过这些注解整合模型名称、描述和属性详情,可以简化准确详细的 API 文档编制工作。
- 验证:利用
@ApiModelProperty
可以定义验证约束,如最大长度或最小值,帮助确保数据的完整性。 - 模型解读:在生成的 API 指南中,
@ApiModel
和@ApiModelProperty
提供的信息有助于明确展示模型,包括示例和详细描述。
注解应用指南
@ApiModel
的注解用法如下:
属性 | 数据类型 | 默认值 | 说明 |
---|---|---|---|
value | String | "" | 模型的名称 |
description | String | "" | 模型的描述 |
parent | Class<?> | Void.class | 模型的父类 |
discriminator | String | "" | 模型的鉴别器 |
subTypes | Class<?>[] | {} | 模型的子类 |
reference | String | "" | 模型的引用 |
example | String | "" | 模型的示例 |
另一方面,@ApiModelProperty
的使用注解如下:
属性 | 数据类型 | 默认值 | 说明 |
---|---|---|---|
value | String | "" | 属性的名称 |
name | String | "" | 属性的名称 |
dataType | String | "" | 属性的数据类型 |
required | boolean | FALSE | 属性是否必需 |
example | String | "" | 属性的示例 |
hidden | boolean | FALSE | 属性是否隐藏 |
allowableValues | String | "" | 属性的允许值范围 |
access | String | "" | 属性的访问权限 |
notes | String | "" | 属性的注释 |
position | int | 0 | 属性的位置 |
实践案例
考虑在一个用户管理系统中的用户模型,需要为其 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,并通过多端同步方便测试和维护。
最后感谢每一个认真阅读我文章的人,礼尚往来总是要有的,虽然不是什么很值钱的东西,如果你用得到的话可以直接拿走:
这些资料,对于【软件测试】的朋友来说应该是最全面最完整的备战仓库,这个仓库也陪伴上万个测试工程师们走过最艰难的路程,希望也能帮助到你!
相关文章:
深入了解Swagger注解:@ApiModel和@ApiModelProperty实用指南
在现代软件开发中,提供清晰全面的 API 文档 至关重要。ApiModel 和 ApiModelProperty 这样的代码注解在此方面表现出色,通过增强模型及其属性的元数据来丰富文档内容。它们的主要功能是为这些元素命名和描述,使生成的 API 文档更加明确。 Api…...
Linux学习第48天:Linux USB驱动试验:保持热情,保持节奏,持续学习是作为一个技术人员应有的基本素质和要求
Linux版本号4.1.15 芯片I.MX6ULL 大叔学Linux 品人间百味 思文短情长 最近更新的速度和频率大不如以前,主要原因还是自己有些懈怠了。学习是一个持续努力的过程,一旦中断,再想保持以往的状态可能要…...
数据库索引简析
文章目录 前言一、索引是什么二、索引的有什么用三、索引的分类四、索引的数据结构总结 前言 在我们使用数据库的过程中,往往会碰到一个叫做索引的东西,不管是表的设计,还是数据库性能的优化往往都会涉及到索引。那么他是个什么东西ÿ…...
leetcode贪心(单调递增的数字、监控二叉树)
738.单调递增的数字 给定一个非负整数 N,找出小于或等于 N 的最大的整数,同时这个整数需要满足其各个位数上的数字是单调递增。 (当且仅当每个相邻位数上的数字 x 和 y 满足 x < y 时,我们称这个整数是单调递增的。ÿ…...
如何在win7同样支持Webview2 在 WPF 中使用本地 Webview2 ,如何不依赖系统 Runtime
项目运行环境: .Net Framework 4.5.2 Windows 7 x64 Service Pack 1 WebView2 Microsoft.WebView2.FixedVersionRuntime.120.0.2210.91.x64 考虑到很多老项目,本项目使用的是.Net Framework 4.5.2,.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、配置国标…...
技术发展驱动编程语言走向
未来编程语言的走向可能会受到多种因素的影响,包括技术进步、市场需求、开发人员的偏好和生态系统的演变等。以下是一些可能的发展趋势: 简洁性和易用性 随着技术的进步,编程语言可能会变得越来越简洁和易于使用。一些语言可能会引入更高级的…...
tp5+workman(GatewayWorker) 安装及使用
一、安装thinkphp5 1、宝塔删除php禁用函数putenv、pcntl_signal_dispatch、pcntl_wai、pcntl_signal、pcntl_alarm、pcntl_fork,执行安装命令。 composer create-project topthink/think5.0.* tp5 --prefer-dist 2、配置好站点之后,浏览器打开访问成…...
vscode安装Prettier插件,对vue3项目进行格式化
之前vscode因为安装了Vue Language Features (Volar)插件,导致Prettier格式化失效,今天有空,又重新设置了一下 1. 插件要先安装上 2. 打开settings.json {"editor.defaultFormatter": "esbenp.prettier-vscode","…...
macOS跨进程通信: XPC 创建实例
一:简介 XPC 是 macOS 里苹果官方比较推荐和安全的的进程间通信机制。 集成流程简单,但是比较绕。 主要需要集成 XPC Server 这个模块,这个模块最终会被 apple 的根进程 launchd 管理和以独立进程的方法唤起和关闭, 我们主app 进…...
Ubuntu18.04 升级Ubuntu20.04
文章目录 背景升级方法遇到的问题 背景 因项目环境需要,欲将Ubuntu18.04升级至Ubuntu20.04,参考网上其他小伙伴的方法,也遇到了一个问题,特此记录一下,希望能帮助其他有同样问题的小伙伴。 升级方法 参考:…...
自动化测试怎么做?看完你就懂了。。。
前言 我想应该有很多测试人员应该有这样的疑虑,自动化测试要怎么去做,现在我把自己的一些学习经验分享给大家,希望对你们有帮助,有说的不好的地方,还请多多指教! 对于测试人员来说,不管进行功…...
小秋SLAM入门实战opencv所有文章汇总
opencv_core和 opencv_imgcodecs是 OpenCV(开源计算机视觉库)的两个主要模块 【如何使用cv::erode()函数对图像进行腐蚀操作】 头文件用途 用OpenCV创建一张类型为CV_8UC1的单通道随机灰度图像 用OpenCV创建一张灰度黑色图像并设置某一列为白色 OpenCV创…...
2023年终总结(脚踏实地,仰望星空)
回忆录 2023年,经历非常多的大事情,找工作、实习、研究生毕业、堂哥结婚、大姐买车、申博、读博、参加马拉松,有幸这一年全家人平平安安,在稳步前进。算是折腾的一年,杭州、赣州、武汉、澳门、珠海、遵义来回跑。完成…...
Transforer逐模块讲解
本文将按照transformer的结构图依次对各个模块进行讲解: 可以看一下模型的大致结构:主要有encode和decode两大部分组成,数据经过词embedding以及位置embedding得到encode的时输入数据 输入部分 embedding就是从原始数据中提取出单词或位置&…...
macOS进程间通信的常用技术汇总
macOS进程间通信的常用技术汇总 命令行传参。yyds管道(pipe), 匿名管道, c的技术,可以跨平台使用 只能在父子进程间通信,由于是单向的管道,只能单方面传输数据。 如果需要双向传输,需要建立双向的两条管道才行 匿名管…...
高德地图信息窗体设置
1. 添加默认信息窗体 //构建信息窗体中显示的内容var info [];info.push(<div style"height: 36px; line-height: 45px; padding: 0px 20px; white-space:nowrap;">位置:北京</div>);info.push(<div style"height: 36px; line-heig…...
isEmpty 和 isBlank 的用法区别,居然一半的人答不上来.....
isEmpty 和 isBlank 的用法区别 isEmpty系列isBank系列 hi!我是沁禹~ 也许你两个都不知道,也许你除了isEmpty/isNotEmpty/isNotBlank/isBlank外,并不知道还有isAnyEmpty/isNoneEmpty/isAnyBlank/isNoneBlank的存在, come on ,让我们一起来探索org.apache…...
数据分析求职-简历准备
简历在整个求职过程中的重要性不言而喻,今天咱们来聊求职过程中简历准备的那些事儿~ 1. 简历究竟有啥用 求职的流程简单说就是:网申->笔试->面试->offer 其中网申环节,简历100%决定了你的通过与否,这个点大家都知道。…...
亚马逊店铺遇到账号申诉模版分享
1.表达诚意,先认错再说:我知道,最近我们在Amazon.com上作为卖家的表现已经低于亚马逊和我们自己的质量标准。 2.清楚分明的格式:我们库存管理的混乱导致了延迟发货,更糟糕的是,物品无法使用。当延迟发货和…...
2023年广东省网络安全A模块(笔记详解)
模块A 基础设施设置与安全加固 一、项目和任务描述: 假定你是某企业的网络安全工程师,对于企业的服务器系统,根据任务要求确保各服务正常运行,并通过综合运用登录和密码策略、流量完整性保护策略、事件监控策略、防火墙策略等多…...
竞赛保研 基于机器视觉的银行卡识别系统 - opencv python
1 前言 🔥 优质竞赛项目系列,今天要分享的是 基于深度学习的银行卡识别算法设计 该项目较为新颖,适合作为竞赛课题方向,学长非常推荐! 🧿 更多资料, 项目分享: https://gitee.com/dancheng…...
书摘:C 嵌入式系统设计模式 04
本书的原著为:《Design Patterns for Embedded Systems in C ——An Embedded Software Engineering Toolkit 》,讲解的是嵌入式系统设计模式,是一本不可多得的好书。 本系列描述我对书中内容的理解。 实现类的最简单方法是使用文件作为封装…...
C 练习实例16 - 最大公约数和最小公倍数
题目:输入两个正整数a和b,求其最大公约数和最小公倍数 数学:最大公约数*最小公倍数a*b 例如:a16,b20。最小公倍数80,最大公约数4。80*416*20。 算法:辗转相除法,又称欧几里德算法…...
GAN-概念和应用场景
概念和应用 生成对抗网络 (GAN) 的 18 个令人印象深刻的应用 by 杰森布朗利 on July 12, 2019 in 生成对抗网络110 鸣叫 共享 生成对抗网络 (GAN) 是一种用于生成建模的神经网络架构。 生成式建模涉及使用模型生成可…...
LeetCode(36)有效的数独 ⭐⭐
请你判断一个 9 x 9 的数独是否有效。只需要 根据以下规则 ,验证已经填入的数字是否有效即可。 数字 1-9 在每一行只能出现一次。数字 1-9 在每一列只能出现一次。数字 1-9 在每一个以粗实线分隔的 3x3 宫内只能出现一次。(请参考示例图) 注…...
用LCD显示字符‘A‘
#include<reg51.h> //包含单片机寄存器的头文件 #include<intrins.h> //包含_nop_()函数定义的头文件 sbit RSP2^0; //寄存器选择位,将RS位定义为P2.0引脚 sbit RWP2^1; //读写选择位,将RW位定义为P2.1引脚 sbit EP2^2; //使能…...
Zookeeper相关问题及答案(2024)
1、ZooKeeper是什么?它的主要用途是什么? ZooKeeper 是一个由 Apache 预先开发和维护的开源服务器,用于协调分布式应用程序。它是一个集中式服务,为分布式应用提供一致性保障,配置管理,命名,同…...
1.大数据概述
目录 概述hadoophadoop 模块hadoop 发行版apache社区版本CDP(CDHHDP)其它云产商框架选择 hadoop 安装 结束 概述 先了解几个常用的网站 apache 官网hadoop 官网hadoop githubhttps://github.com/apache/xxx [https://github.com/apache/spark (example)] hadoop hadoop 模块…...
商务型网站有哪些/精准营销案例
1.应用场景 c语言精通了能干什么? 1、C语言是许多高级计算机语言的基础,学好C语言能更好的学习其他高级语言,为以后的学习打基础;往深学C语言的话那就是学到C在Linux里的应用,Linux十分强大,可以百度了解。 2、C语言是…...
网站的开发方法有哪些/seo实战培训视频
2019独角兽企业重金招聘Python工程师标准>>> 1. 背景 1.1. 原生NIO类库的复杂性 在开始本文之前,我先讲一件自己亲身经历的事:大约在2011年的时候,周边的两个业务团队同时进行新版本开发,他们都需要基于NIO非阻塞特性构…...
怎么查看一个网站是谁做的/怎样做app推广
Python之建模数值逼近篇–最小二乘拟合介绍系数ak的确定函数rk(x)r_k(x)rk(x)的选取理解和区别样例介绍 曲线拟合问题的提法是,已知一组(二维)数据,即平面上的n个点(xi,yi)(x_{i},y_{i})(xi,yi),i1,2,…,n,xix_…...
宝应123网站建设网/seo排名优化推广教程
---恢复内容开始--- ---恢复内容结束---转载于:https://www.cnblogs.com/houzhitong/archive/2013/04/03/2998172.html...
西部数码网站管理助手v4.0/株洲发布最新通告
堆的定义 其实堆也是树,但是必选满足以下两点: 堆是一棵完全二叉树 完全二叉树就是除了最后一层,其他层的节点个数都是满的,最后一层的节点都靠左排列。 堆中的每个节点值都必须大于等于(或小于等于)其子…...
真正免费的网站建站平台排名/百度官网优化
今天在进行依赖安装的的时候,出现了一个nodejieba的报错,报错信息如下 node-pre-gyp WARN Using request for node-pre-gyp https download node-pre-gyp WARN Tried to download(404): https://github.com/yanyiwu/nodejieba/releases/download/2.4.1…...