当前位置: 首页 > 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;这个点大家都知道。…...

观成科技:隐蔽隧道工具Ligolo-ng加密流量分析

1.工具介绍 Ligolo-ng是一款由go编写的高效隧道工具&#xff0c;该工具基于TUN接口实现其功能&#xff0c;利用反向TCP/TLS连接建立一条隐蔽的通信信道&#xff0c;支持使用Let’s Encrypt自动生成证书。Ligolo-ng的通信隐蔽性体现在其支持多种连接方式&#xff0c;适应复杂网…...

MPNet:旋转机械轻量化故障诊断模型详解python代码复现

目录 一、问题背景与挑战 二、MPNet核心架构 2.1 多分支特征融合模块(MBFM) 2.2 残差注意力金字塔模块(RAPM) 2.2.1 空间金字塔注意力(SPA) 2.2.2 金字塔残差块(PRBlock) 2.3 分类器设计 三、关键技术突破 3.1 多尺度特征融合 3.2 轻量化设计策略 3.3 抗噪声…...

DeepSeek 赋能智慧能源:微电网优化调度的智能革新路径

目录 一、智慧能源微电网优化调度概述1.1 智慧能源微电网概念1.2 优化调度的重要性1.3 目前面临的挑战 二、DeepSeek 技术探秘2.1 DeepSeek 技术原理2.2 DeepSeek 独特优势2.3 DeepSeek 在 AI 领域地位 三、DeepSeek 在微电网优化调度中的应用剖析3.1 数据处理与分析3.2 预测与…...

mongodb源码分析session执行handleRequest命令find过程

mongo/transport/service_state_machine.cpp已经分析startSession创建ASIOSession过程&#xff0c;并且验证connection是否超过限制ASIOSession和connection是循环接受客户端命令&#xff0c;把数据流转换成Message&#xff0c;状态转变流程是&#xff1a;State::Created 》 St…...

【JVM】- 内存结构

引言 JVM&#xff1a;Java Virtual Machine 定义&#xff1a;Java虚拟机&#xff0c;Java二进制字节码的运行环境好处&#xff1a; 一次编写&#xff0c;到处运行自动内存管理&#xff0c;垃圾回收的功能数组下标越界检查&#xff08;会抛异常&#xff0c;不会覆盖到其他代码…...

Java - Mysql数据类型对应

Mysql数据类型java数据类型备注整型INT/INTEGERint / java.lang.Integer–BIGINTlong/java.lang.Long–––浮点型FLOATfloat/java.lang.FloatDOUBLEdouble/java.lang.Double–DECIMAL/NUMERICjava.math.BigDecimal字符串型CHARjava.lang.String固定长度字符串VARCHARjava.lang…...

基于数字孪生的水厂可视化平台建设:架构与实践

分享大纲&#xff1a; 1、数字孪生水厂可视化平台建设背景 2、数字孪生水厂可视化平台建设架构 3、数字孪生水厂可视化平台建设成效 近几年&#xff0c;数字孪生水厂的建设开展的如火如荼。作为提升水厂管理效率、优化资源的调度手段&#xff0c;基于数字孪生的水厂可视化平台的…...

解决本地部署 SmolVLM2 大语言模型运行 flash-attn 报错

出现的问题 安装 flash-attn 会一直卡在 build 那一步或者运行报错 解决办法 是因为你安装的 flash-attn 版本没有对应上&#xff0c;所以报错&#xff0c;到 https://github.com/Dao-AILab/flash-attention/releases 下载对应版本&#xff0c;cu、torch、cp 的版本一定要对…...

OpenLayers 分屏对比(地图联动)

注&#xff1a;当前使用的是 ol 5.3.0 版本&#xff0c;天地图使用的key请到天地图官网申请&#xff0c;并替换为自己的key 地图分屏对比在WebGIS开发中是很常见的功能&#xff0c;和卷帘图层不一样的是&#xff0c;分屏对比是在各个地图中添加相同或者不同的图层进行对比查看。…...

GC1808高性能24位立体声音频ADC芯片解析

1. 芯片概述 GC1808是一款24位立体声音频模数转换器&#xff08;ADC&#xff09;&#xff0c;支持8kHz~96kHz采样率&#xff0c;集成Δ-Σ调制器、数字抗混叠滤波器和高通滤波器&#xff0c;适用于高保真音频采集场景。 2. 核心特性 高精度&#xff1a;24位分辨率&#xff0c…...