Swagger注解-@ApiParam

最新推荐文章于 2025-11-06 11:45:00 发布
原创 最新推荐文章于 2025-11-06 11:45:00 发布 · 8.5w 阅读 · 79 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#Swagger #Swagger注解 #@ApiParam

本文深入讲解Swagger注解的使用，包括@ApiOperation、@ApiImplicitParams等，帮助开发者为REST接口添加详细元数据，提升API文档的清晰度和可用性。

Swagger注解-@Api
Swagger注解-@ApiOperation
Swagger注解-@ApiImplicitParams 和 @ApiImplicitParam
Swagger注解-@ApiModel 和 @ApiModelProperty
Swagger注解-@ApiResponses 和 @ApiResponse
Swagger注解-@ResponseHeader
Swagger注解-@ApiParam
Swagger注解-@Authorization 和 @AuthorizationScope
Swagger注解-@SwaggerDefinition
Swagger注解-@ExternalDocs
Springboot 集成 Swagger GitHub 地址

使用场景

在 Rest 接口上或 Rest 接口参数前边使用

概述

为 Rest 接口参数添加其它元数据(导入到 yapi 中不会被解析)

属性

属性名称数据类型默认值说明
nameString“”参数名称，参数名称将从 filed/method/parameter 名称中派生，但你可以覆盖它，路径参数必须始终命名为它们所代表的路径部分
valueString“”参数简单描述
defaultValueString“”描述参数默认值
allowableValuesString“”可接收参数值限制，有三种方式,取值列表，取值范围
requiredbooleanfalse是否为必传参数, false:非必传; true:必传
accessString“”参数过滤，请参阅:io.swagger.core.filter.SwaggerSpecFilter
allowMultiplebooleanfalse指定参数是否可以通过多次出现来接收多个值
hiddenbooleanfalse隐藏参数列表中的参数
exampleString“”非请求体(body)类型的单个参数示例
examplesExample@Example(value = @ExampleProperty(mediaType = “”, value = “”))参数示例，仅适用于请求体类型的请求
typeString“”添加覆盖检测到类型的功能
formatString“”添加提供自定义format格式的功能
allowEmptyValuebooleanfalse添加将格式设置为空的功能
readOnlybooleanfalse添加被指定为只读的能力
collectionFormatString“”添加使用 array 类型覆盖 collectionFormat 的功能

Swagger注解-@Api
Swagger注解-@ApiOperation
Swagger注解-@ApiImplicitParams 和 @ApiImplicitParam
Swagger注解-@ApiModel 和 @ApiModelProperty
Swagger注解-@ApiResponses 和 @ApiResponse
Swagger注解-@ResponseHeader
Swagger注解-@ApiParam
Swagger注解-@Authorization 和 @AuthorizationScope
Swagger注解-@SwaggerDefinition
Swagger注解-@ExternalDocs
Springboot 集成 Swagger GitHub 地址

@ApiParam详解：用注解玩转API参数，让接口文档更清晰！
**My Coding Family**
06-04 871
🏆本文收录于「滚雪球学SpringBoot」专栏，手把手带你零基础入门Spring Boot，从入门到就业，助你早日登顶实现财富自由🚀；同时，欢迎大家关注&&收藏&&订阅！持续更新中，up！up！up！！
Swagger3.0.0实战
Java__EE小白成长之路
05-16 6013
springboot2.6.4+基于knife4j增强的Swagger3.0.0实现
spring boot 获取HTTP 请求参数
最新发布
chxii的专栏
11-06 2196
本文总结了Spring中获取HTTP请求参数的5种方式：路径参数(@PathVariable)、查询参数(@RequestParam)、请求体(@RequestBody)、表单参数和请求头(@RequestHeader)。详细介绍了每种参数的使用场景、注解配置和注意事项，特别说明了Map接收参数的场景和限制。文章还比较了Map和POJO两种接收方式的适用情况，强调要根据参数结构是否固定、是否需要校验等实际需求选择合适的方式。最后提供了完整示例代码，帮助开发者灵活处理各种请求参数场景。
@RequestParam @PathVirable @RequestBody @ApiParam的区别
qq_44886213的博客
10-11 730
这是swagger3提供的注解，基本上没人用。也是swagger版本的@RequstParam。使用swagger的时候才用得到这个注解，相当于swagger版本的@RequstParam。
【注解】@ApiParam @PathVariable @RequestParam
hoiyaku
09-05 8788
1.@ApiParam ，是注解api的参数，用于swagger提供开发者文档，文档中生成的注释内容。 @ApiOperation(value = "根据id查询") @GetMapping(value = {"/findById/{id}"}) public ItooResult findById(@ApiParam(value = "主键id", required = ...
Swagger常见注解@API、@ApiOperation、@ApiParam等
热门推荐
瓜皮康的博客
04-26 10万+
Swagger2一些常用注解 最近遇到了一个使用swagger来生成接口文档的项目，在controller看到了一些没用过的注解（@API、@ApiOperation等），遂记录一下 @API使用在类上，表明是swagger资源 拥有两个属性:value、tags，源码如下 //If tags is not used,this value will be used to set the tag...
Java中注解@RequestParam 和 @ApiParam详解
VIP_1205169154的博客
03-08 3684
ApiParam示例：pandas 是基于NumPy 的一种工具，该工具是为了解决数据分析任务而创建的。
Pont神坑 ，添加swagger @ApiParam后无法导出参数
applebomb的专栏
03-17 393
今天正在整Pont的时候，发现个别API参数在pont里无法导出，经过反复的对比发现。只要使用了@ApiParam或@ApiImplicitParam的参数，都无法正常被pont导出。使用swagger参数注解的项格式有点小变化，例如type放到了schema项之内。可能这个差异导致了pont解析不出来吧。目前暂时的解决方法就是，不使用@ApiParam和@ApiImplicitParam注解。可能 Swagger V3接口可以正常吧，暂时不调整了。被@ApiParam注解的项，无法被正常导出。
使用了Swagger的@ApiParam会发生无法正常传入参数的问题
elapse_的博客
02-11 2564
在写一个需要传参验证功能时。 public ResultBean verify(@ApiParam("手机号码")String phoneNumber, @ApiParam("验证码")String userCode) 在没有使用ApiParam参数之前可以正常进行传参功能，但是使用了此注解后发现传参格式会自动变成json格式，然后就无法正常直接输入传参。 会发生以下问题： 也就是传输为null，传不进去。需要将代码写成这个格式： public ResultBean verify(@ApiParam("
关于swagger注解@ApiParam 和 @ApiImplicitParam 的问题
yeshenyuexieriji的博客
11-18 1万+
本次记录源于遇到的以下问题： 如图所示，在接口的controller层我需要设置传入的参数dataType： 1、直接在括号中设置参数； 2、在方法的上面加上ApiImplicitParam注解，通过name属性设置参数的名称，通过paraType设置参数的请求类型； 两种方式呈现在swagger前端页面的时候请求类型其实是query 但是此时我想给括号中的参数设置一些参数说明，所以加上了@ApiParam注解，此时问题出现了： @ApiParam注解加上之后参数的请求类型变成了Body类型，这让我有
使用swagger 2.9.2版本，注解@ApiParam出现的问题
weixin_43665278的博客
12-18 3943
在前后端分离的项目中，为了便捷开发，很多项目中会用到swagger这个工具，其中使用@ApiParam在项目启动后访问swagger页面的时候出现了这样一个问题。 接口层代码： @Api(description = "运动等级体系接口") @Slf4j @RestController @RequestMapping("/SportSystem") public class SportSystemC...
注解@Api,@ApiOperation,@ApiParam说明
weixin_38345306的博客
04-15 1万+
swagger的一些注释： 1.@API 是用在类上，表明是swagger资源， 拥有两个属性：value、tags 注：生成的api文档会根据tags分类，即这个controller中的所有接口生成的接口文档都会在tags这个list下；tags如果有多个值，会生成多个list,每个list都显示所有接口 value的作用类似tags,但不能有多个值 2.@ApiOperation 是用在方法上，表示一个http请求的操作 value用于方法描述 notes用于提示内容 tags可以重新分组 3.@Api
Swagger学习⑦——@Parameter注解
一个写了10年bug的程序员日常笔记。
01-03 2855
Parameter注解是库的一部分，属于。它用于描述 API 操作中的参数，包括查询参数、路径参数、请求头参数等。通过@Parameter注解，可以为参数提供详细的元数据，例如描述、是否必需、示例值等，从而生成更清晰的 OpenAPI 文档。
@RequestParam和 @ApiParam注解使用
qq_43960622的博客
08-03 1万+
@RequestParam和 @ApiParam注解使用
@ApiParam @PathVariable @RequestParam三者区别
aocheqing0591的博客
07-20 608
转载：https://www.cnblogs.com/xu-lei/p/7803062.html @ApiParam @PathVariable @RequestParam三者区别 1.@ApiParam 顾名思义，是注解api的参数，也就是用于swagger提供开发者文档，文档中生成的注释内容。 @ApiOperation( value = "编辑公告", notes ...
Swagger 常用注解使用详解2：@ApiParam @PathVariable @RequestParam三者区别
香草天空Sky的博客
07-27 2万+
1.@ApiParam 顾名思义，是注解api的参数，也就是用于swagger提供开发者文档，文档中生成的注释内容。 　　 @ApiOperation( value = "编辑公告", notes = "编辑公告", httpMethod = "POST" ) @RequestMapping( value = "/edit", method = RequestMethod.POST ...
Swagger学习⑧——@Parameters注解
一个写了10年bug的程序员日常笔记。
01-03 1560
注解是库的一部分，属于。它用于在 API 操作中同时描述多个参数。与@Parameter注解不同，是一个容器注解，可以包含多个@Parameter注解，从而更简洁地描述多个参数。
Swagger常见注解@API、@ApiOperation、@ApiParam
weixin_57763462的博客
07-26 2366
Swagger2一些常用注解 最近遇到了一个使用swagger来生成接口文档的项目，在controller看到了一些没用过的注解（@API、@ApiOperation等），遂记录一下 @API 使用在类上，表明是swagger资源，@API拥有两个属性:value、tags，源码如下 //If tags is not used,this value will be used to set the tag for the operations described by this resource. Othe
swagger3 @ApiParam
03-28
<think>好的，我现在需要回答用户关于在Swagger3中正确使用@ApiParam注解的问题。用户希望了解具体的用法、示例以及参数说明。首先，我需要回顾一下Swagger3的基本知识，尤其是与注解相关的内容。 根据用户提供的引用资料，特别是引用[2]和[3]，@ApiParam和@RequestParam有不同的用途。@ApiParam主要用于生成API文档，而@RequestParam用于处理HTTP请求参数。因此，在Swagger3中，@ApiParam的作用应该是描述接口参数的信息，帮助生成更清晰的文档。 接下来，我需要确认Swagger3中@ApiParam的用法是否与Swagger2有差异。引用[4]提到，虽然Swagger3和Swagger2在使用方式上有些小变动，但总体流程相似。因此，大部分参数应该保持一致，但需要检查是否有新增或弃用的属性。 用户需要示例和参数说明，我应该先给出一个基本的代码示例，展示如何在方法参数前添加@ApiParam注解。例如，在Spring Boot的Controller中，使用@ApiParam注解来描述一个查询参数，比如用户的姓名。然后，详细说明每个参数的意义，如name、value、required、example等。 同时，需要注意Swagger3是否引入了新的参数或者改变了某些属性的名称。例如，在Swagger2中，paramType用于指定参数类型的位置（如query、path等），而在Swagger3中是否需要调整？根据引用[3]中的示例，paramType的值是字符串，但可能需要使用更标准的类型，比如query、path等，可能需要确认正确的用法。 另外，是否需要结合其他注解，比如@Parameter（来自OpenAPI的注解）来替代@ApiParam？因为Swagger3是基于OpenAPI 3.0的，可能推荐使用新的注解。不过用户特别询问的是@ApiParam，所以可能仍需说明其在Swagger3中的使用方式，同时指出是否有替代方案。 还需要注意，Swagger3的依赖是否有所变化。比如，Spring Boot集成Swagger3可能需要不同的starter依赖，比如springdoc-openapi-ui，而不是原来的springfox。这可能影响注解的包路径，比如io.swagger.v3.oas.annotations而不是io.swagger.annotations。但用户的问题集中在注解的使用，而不是环境配置，所以可能需要简要提到包路径的变化，但主要关注注解参数。 总结步骤： 1. 说明@ApiParam的基本用途，与@RequestParam的区别。 2. 提供一个使用@ApiParam的代码示例，展示在方法参数上的应用。 3. 列举@ApiParam的常用参数及其作用，如name、value、required、example等。 4. 对比Swagger2和Swagger3中的差异，如果有的话。 5. 提示依赖变化和包路径的不同。 6. 生成相关问题，引导用户进一步学习。 需要确保回答结构清晰，步骤明确，参数说明详细，并且示例正确。同时，引用提供的资料来支持说明，比如引用[2]和[3]中的内容，确保信息准确。</think>在 Swagger 3 中，`@ApiParam` 注解用于描述接口参数的信息，帮助生成更清晰的 API 文档。以下是具体用法和参数说明： --- ### **1. 基本用法** `@ApiParam` 通常标注在控制器方法的参数上，结合 `@RequestParam` 或 `@PathVariable` 使用。例如： ```java @GetMapping("/user") public User getUser( @ApiParam(name = "name", value = "用户姓名", required = true, example = "张三") @RequestParam String name) { // 业务逻辑 } ``` --- ### **2. 核心参数说明** | 参数 | 说明 | 示例值 | |-------------|----------------------------------------------------------------------|-------------------------------| | `name` | 参数名称，需与代码中的变量名一致 | `name = "userId"` | | `value` | 参数的描述信息 | `value = "用户唯一ID"` | | `required` | 参数是否必填，默认为 `false` | `required = true` | | `example` | 示例值，展示在文档中 | `example = "1001"` | | `allowEmptyValue` | 是否允许空值，默认 `false` | `allowEmptyValue = true` | --- ### **3. 与 Swagger2 的区别** - **包路径变化**：Swagger3 的注解位于 `io.swagger.v3.oas.annotations` 包下，需确保依赖正确。例如： ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> ``` - **兼容性**：Swagger3 兼容 OpenAPI 3.0 规范，但部分旧注解可能被弃用，推荐使用 `@Parameter`（功能更强大）[^4]。 --- ### **4. 注意事项** - **与 `@RequestParam` 的协作**：`@ApiParam` 仅用于文档生成，不处理请求逻辑，需配合 `@RequestParam` 或 `@PathVariable` 使用[^2]。 - **参数类型明确性**：若参数是复杂对象（如 JSON 请求体），应使用 `@RequestBody` 和 `@ApiModelProperty` 代替[^1]。 --- ### **示例场景** ```java @PostMapping("/update") public void updateUser( @ApiParam(name = "id", value = "用户ID", required = true, example = "1001") @RequestParam Long id, @ApiParam(name = "role", value = "用户角色", allowableValues = "admin, user", example = "admin") @RequestParam String role) { // 更新用户角色逻辑 } ``` 此示例会在 Swagger UI 中生成两个查询参数，分别描述 ID 和角色。 ---
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值