swagger常用注解

最近查看接口文档的时候发现,POST方法中的query没法在swagger中显示,查了才发现这是因为Swagger或OpenAPI规范默认将HTTP POST请求的参数识别为请求体(body)参数,而不是查询字符串(query)参数。这意味着,如果你的POST请求中使用了查询字符串参数并希望在Swagger文档中正确展示它们,你需要明确地通过Swagger注解来指定这些参数是查询参数。因此还是有必要规范swagger注解的。

详细用法

@Api:用在Controller控制器类上value:指定 API 的名称。tags:指定 API 的标签,用于对 API 进行分类。description:描述 API 的功能和作用。produces:指定 API 的响应内容类型。consumes:指定 API 接受的请求内容类型。authorizations:指定 API 的安全认证要求。hidden:指定是否隐藏该 API@ApiOperation:用在Controller控制器类的请求的方法上value:对该操作进行简单的描述,尽量控制在120字符以内notes:对操作的详细描述httpMethod:指定操作使用的HTTP方法类型,可选值 “GET”、“HEAD”、“POST”、“PUT”、“DELETE”、“OPTIONS”和“PATCH”tags:用来给操作打标签,Swagger UI 将在操作列表下面展示 tag 列表,每个 tag 下面展示拥有该 tag 的操作列表。(就是分组)@ApiImplicitParams:用在请求的方法上,表示一组参数说明@ApiImplicitParam:请求方法中参数的说明name:参数名value:参数的汉字说明、解释、用途required:参数是否必须传,布尔类型paramType:参数的类型,即参数存储位置或提交方式· header --> Http的Header携带的参数的获取:@RequestHeader· query --> 请求参数的获取:@RequestParam · path(用于restful接口)--> 请求参数的获取:@PathVariable· body(不常用)· form(不常用)    dataType:参数类型,默认String,其它值dataType="Integer"       defaultValue:参数的默认值@ApiResponses:用在控制器的请求的方法上,对方法的响应结果进行描述@ApiResponse:用于表达一个响应信息code:数字,例如400message:信息,例如"请求参数没填好"response:响应结果封装类,如上例子中的AjaxResponse.class@ApiModel:通常用在描述@RequestBody和@ResponseBody注解修饰的接收参数或响应参数实体类value:属性值,也就是该实体类的描述值,不写默认为实体类的名称,通常描述不清晰才需要value值description:描述值,与value不同,该description为较长描述值parent:用于指定被注解类的父类discriminator:多态情境区分多个子类subTypes:指定被注解类的子类reference:提供对被注解类的引用信息@ApiModelProperty:实体类属性的描述value:注解的默认属性,理解为注释的作用name:指定属性或方法的名称,重写该属性名字allowableValues:指定属性或方法的可接受值范围。access:指定属性或方法的访问规则。notes:提供对属性或方法的额外说明。dataType:指定属性或方法的数据类型。required:指定属性或方法是否为必需。position:指定属性或方法在文档中的位置。hidden:指定属性或方法是否应该在文档中隐藏。example:提供属性或方法的示例值。readOnly(已过时):指定属性或方法是否为只读。已过时,推荐使用 access 属性。accessMode:指定访问模式,可以是 AUTO、READ_ONLY 或 READ_WRITE。reference:提供属性或方法的引用信息。allowEmptyValue:指定属性或方法是否允许为空值。extensions:指定属性或方法的扩展信息,支持一组扩展属性。AccessMode枚举:属性或方法的访问模式,包括 AUTO、READ_ONLY 和 READ_WRITE。

一个实例

Controller 示例

假设我们有一个处理图书信息的API。

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;@RestController
@Api(value = "Books Controller", tags = {"Books"})
@Slf4j
@RequestMapping("/book")
public class BooksController {@ApiOperation(value = "Get book by ID", notes = "Provides a book's details by its ID")@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "Book ID", required = true, dataType = "long", paramType = "query")})@GetMapping("/books")public BookResponse getBookById(Long id) {// 模拟查询书籍逻辑return new BookResponse(1L, "示例书名", "示例作者", "这是一个示例描述。");}@ApiOperation(value = "Create a new book", notes = "Creates a new book with the provided information")@PostMapping("/books")public BookResponse createBook(@RequestBody BookRequest bookRequest) {// 模拟书籍创建逻辑return new BookResponse(bookRequest.getId(), bookRequest.getTitle(), bookRequest.getAuthor(), bookRequest.getDescription());}
}

Request 示例

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;@Data
@ApiModel(description = "Book creation request")
public class BookRequest {@ApiModelProperty(value = "The ID of the book", required = true)private Long id;@ApiModelProperty(value = "The title of the book", required = true)private String title;@ApiModelProperty(value = "The author of the book")private String author;@ApiModelProperty(value = "The description of the book")private String description;// 构造函数、Getter和Setter方法省略
}

Response 示例

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;@Data
@ApiModel(description = "Book response containing book details")
public class BookResponse {@ApiModelProperty(value = "The ID of the book")private Long id;@ApiModelProperty(value = "The title of the book")private String title;@ApiModelProperty(value = "The author of the book")private String author;@ApiModelProperty(value = "The description of the book")private String description;public BookResponse(Long id, String title, String author, String description) {this.id = id;this.title = title;this.author = author;this.description = description;}// Getter和Setter方法省略
}

在这个例子中,BooksController类包括了两个API端点:一个用于通过ID获取书籍详细信息的GET请求,另一个用于创建新书籍的POST请求。BookRequest和BookResponse类分别用于API请求和响应的数据模型,它们通过使用@ApiModel和@ApiModelProperty注解来提供字段的描述以增强自动生成的Swagger(OpenAPI)文档的可读性。

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

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

相关文章

javaScript 计算以过去的时间

1.找到当前的时间的 new Data()//获取现在的时间毫秒数 2.找到过去的一个时间 new Data(time)//获取过去时间点的毫秒数 3.(现在的时间(毫秒) - 过去的时间点(毫秒))/1000 已过去的时间(秒) var …

postGreSQL关系数据库介绍

什么是postGreSQL关系数据库? PostgreSQL 是一个强大的、开源的对象关系型数据库管理系统(ORDBMS)。它基于POSTQUEL查询语言的继承,提供了对SQL标准的广泛支持,并扩展了许多高级功能,如事务处理、多版本并…

使用 Webmin 中模块注意事项

一、 Docker中Webmin忘记密码解决方法 Webmin忘记Web登陆时候的密码,无法登陆,可以通过changepass.pl 文件修改密码来进行解决。但在 Docker 中这一方法很难,因为不知道changepass.pl 在那里? 我是通过如下方法来解决的&#xff…

JAVA医院绩效考核系统源码:优化绩效考核的必要性 系统技术架构:java+springboot、mybaits +avue +MySQL

JAVA医院绩效考核系统源码:优化绩效考核的必要性 系统技术架构:javaspringboot、mybaits avue MySQL 医院绩效考核系统,建立以医院发展目标为导向,以医务人员劳动价值、工作量为评价基础,统筹效率、质量、成本的绩效管…

mysql窗口函数选择每个窗口的第一条数据

需求 假设我们有一个名为sales的表,我们想要按product分组,并为每个产品选择销售额最高的那一天 sales表 首先给每个产品按照销售量进行排名 SELECT product,sale_date,sales_amount,ROW_NUMBER() OVER (PARTITION BY product ORDER BY sales_amount …

前端面试题(11)答案版

1. 有没有用过TS? 是的,我有使用过TypeScript。TypeScript是一种强类型的编程语言,在大型项目中可以带来很多好处,比如更好的代码可维护性、更早发现错误等。我在之前的一些项目中都有使用TypeScript。 2. 有没有做过性能优化? 是的,我也做过一些性能优化工作。常见的性能优…

AI在落地企业应用时的“数据幻觉”缘何这么难解决一谈LORA微调与数据质量处理之争

开篇 近年来,随着人工智能技术的飞速发展,越来越多的企业开始将AI落地应用于业务中。然而,不可忽视的是,企业在落地LLM RAG系统时,常常面临一个令人头痛的问题——数据幻觉。 就像透过雾霭的眼睛,看到了一片迷人的景…

IIS 服务器安装SSL证书

IIS 服务器安装SSL证书 步骤一:准备好 SSL 证书 准备好.pfx 格式的证书文件。 步骤二:安装 SSL 证书 1、打开【开始】菜单,找到【管理工具】,打开【Internet 信息服务(IIS)管理器】。 2、单击服务器名…

火山引擎ByteHouse:新一代云数仓必不可少的五大核心能力

从数据库领域的发展历程来看,分析型数据库已有 40 多年的发展历史,与数据库基本同时代。从OLTP 和 OLAP 的分支来看,分析型数据库支持了海量数据规模下的聚合性分析。尤其是随着移动互联网甚至 AI 等领域的发展,用户画像行为分析的…

NGINX配置web文件服务

一、需求描述 系统需要提供文件(pdf、图片)等上传后支持预览功能。 二、实现方式 2.1 文件权限配置 chmod arwx -R public/chmod 是更改文件权限的命令。-R 是递归选项,表示更改目录及其所有子目录和文件的权限。arwx 是权限设置&#xf…

【示例】springboot实现json文件生成,压缩为zip文件并在浏览器下载

FileController GetMapping("/tea/downloadFormula") public ResponseEntity<byte[]> downloadFormula(){logger.info("下载茶类配方, {}", JSONObject.toJSONString(req));List<String> macList req.getMacList();// 创建临时文件根目录Fil…

阿里巴巴找黄金宝箱(IV)

系列文章目录 本人最近再练习算法&#xff0c;所以会发布自己的解题思路&#xff0c;希望大家多指教 文章目录 系列文章目录前言一、题目描述二、输入描述三、输出描述四、java代码五、测试用例 前言 一、题目描述 贫如洗的椎夫阿里巴巴在去砍柴的路上&#xff0c;无意中发现…

一款专为网页开发者设计的高效工具,它简化了响应式网站的开发流程

大家好&#xff0c;今天给大家分享的是一款专为web开发人员和测试人员设计的工具&#xff0c;它通过改进的web浏览器功能&#xff0c;帮助用户进行响应式web开发和兼容性测试。 主要功能 所有设备上的镜像用户交互&#xff1a;允许开发人员在单一设备上进行操作&#xff0c;实时…

Python高精度浮点运算库之mpmath使用详解

概要 在科学计算和工程应用中,精确的数学计算至关重要。Python 作为一种灵活而强大的编程语言,提供了多种数学库,其中 mpmath 库因其高精度浮点运算和丰富的数学函数支持而备受关注。mpmath 库不仅适用于基本的高精度计算,还支持复数运算、矩阵运算和特殊函数计算,广泛应…

使用微信开发者工具创建运行项目全流程

小程序基础知识 1. 认识什么是小程序 什么是微信小程序 微信小程序是一种运行在微信内部的 轻量级 应用程序。 在使用小程序时 不需要下载安装&#xff0c;用户 扫一扫 或 搜一下 即可打开应用。它也体现了 “用完即走” 的理念&#xff0c;用户不用关心安装太多应用的问题…

SyntaxError: Unexpected token ‘<‘ (at chunk-vendors.fb93d34e.js:1:1)打包后页面白屏vue

本地运行一切正常&#xff0c;打包到线上&#xff0c;页面一篇空白。我确定输入路径正确。。。 控制台报错&#xff0c;我就开始百度&#xff0c;有的说清空缓存就行了&#xff0c;但我清空了还是这样。。。 然后我就去排查原因。看到页面请求js&#xff0c;但是请求的好像有点…

技术市集 | 如何通过WSL 2在Windows上挂载Linux磁盘?

你是否常常苦恼&#xff0c;为了传输或者共享不同系统的文件需要频繁地在 Windows 和 Linux 系统之间切换&#xff0c;既耽误工作效率&#xff0c;也容易出错。 那么有没有一种办法&#xff0c;能够让你在Windows系统中像访问本地硬盘一样来操作Linux系统中的文件呢&#xff1…

2024肥晨赠书活动第三期:《前端工程化:基于Vue.js 3.0的设计与实践》

文章目录 内容简介作者简介关于《前端工程化&#xff1a;基于Vue.js 3.0的设计与实践》文章目录文章简介《前端工程化&#xff1a;基于Vue.js 3.0的设计与实践》全书速览结束语 内容简介 本书以Vue.js的3.0版本为核心技术栈&#xff0c;围绕“前端工程化”和TypeScript的知识点…

简单的springboot整合activiti5.22.0

简单的springboot整合activiti5.22.0 1. 需求 我们公司原本的流程服务是本地workflow模块以及一个远程的webService对应的activiti服务&#xff0c;其中activiti版本为5.22.0&#xff0c;之前想将activiiti5.22.0进行升级&#xff0c;选择了camunda&#xff0c;也对项目进行了…

数据处理:数据转译、取小数点后三位

发现一个好用的写法&#xff1a; 一、英转中 <div class"text" v-if"kaBuLe">卡布叻星星&#xff1a;{{ getChinese(kaBuLeType) }} </div>const pageData: {[propName: string]: any } reactive({kaBuLeType:, }) //对应中文 function get…