Swagger注解-@ApiResponses 和 @ApiResponse

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

#Swagger #Swagger注解 #@ApiResponses #@ApiResponse

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 地址

@ApiResponses

代码示例

github 代码示例： https://github.com/CoderFreeMan/swagger-demo

使用场景

在 Rest 接口上使用，用作返回值的描述

概述

一个包装器，允许列出多个 ApiResponse，若果你需要描述单个 ApiResponse，你仍然必须使用此注解并将@ApiResponse 包装在一个数组中

属性

属性名称数据类型默认值说明
valueApiResponse[]ApiResponse 列表

@ApiResponse

使用场景

在 Rest 接口或类上和 @ApiResponses 组合使用，组装返回参数说明

概述

描述操作的可能响应，这可用于描述 Rest API 调用中可能的成功和错误 code 码。此注解可以在方法或类级别应用；仅当在方法级别或抛出时未定义相同代码的@ApiResponse注解时才会解析类级别注解异常，如果响应中使用了不同的响应类，则可以通过将响应类于响应码组合使用。注意swagger不允许单个响应代码的多个响应类型。此注解不直接使用，单独使用时swagger不会解析，应该和ApiResponses组合使用。

属性

属性名称数据类型默认值说明
codeint响应的HTTP状态码
messageString伴随响应的人类可读的消息
responseClass<?>Void.class用于描述消息有效负载的可选响应类，对应于响应消息对象的 schema 字段
referenceString“”指定对响应类型的引用，指定的应用可以使本地引用，也可以是远程引用，将按原样使用，并将覆盖任何指定的response()类
responseHeadersResponseHeader[]@ResponseHeader(name = “”, response = Void.class)可能响应的 header 列表
responseContainerString“”声明响应的容器，有效值为List,Set,Map，任何其他值都将被忽略

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 地址

轻松构建RESTful API：Spring @ResponseBody注解全攻略，有两下子！
**My Coding Family**
05-26 813
🏆本文收录于《滚雪球学Spring Boot》，专门攻坚指数提升，2025 年国内最系统+最强（更新中）。    本专栏致力打造最硬核 Spring Boot 从零基础到进阶系列学习内容，🚀均为全网独家首发，打造精品专栏，专栏持续更新中…欢迎大家订阅持续学习。 如果想快速定位学习，可以看这篇【SpringBoot教程导航帖】,你想学习的都被收集在内，快速投入学习！！两不误。
ApiResponse response = *.class不起作用
猿小白的博客
05-27 1807
此处添加了ApiResponse注解，但在swagger中的响应依然没有数据 目录 一、原因分析 二、解决办法 （1）创建一个泛型实体类 （2）编写一个测试接口 三、再次访问Swagger接口 一、原因分析 AjaxResult是继承的map，Swagger只认识定义好的类-属性，所以接口返回Map,对于Swagger来说是没有字段展示的。 二、解决办法 如需要可以使用泛型类R<T>来解决这个问题。 （1）创建一个泛型实体类 packag...
【转载】Swagger常用注解说明
RubyXun's-Blog
06-09 6067
api标记Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式： 与Controller注解并列使用。 属性配置：在SpringMvc中的配置如下： 2. ApiOperation标记ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式： 与Controller中的方法并列使用。 属性配置：在SpringMvc中的配置如下： 3. ApiParam标记ApiParam...
api-response, 在你的API中，正确处理响应的简单包.zip
09-18
api-response, 在你的API中，正确处理响应的简单包 状态 在你的API中正确处理响应的简单软件包。 这个包使用了分形，并且基于构建 api，你不会讨厌它的。安装通过编辑器$ composer require ellipsesynergie/api-r
Swagger学习⑮——@ApiResponse注解
一个写了10年bug的程序员日常笔记。
01-10 953
是 Swagger 注解库中的一个注解，用于在 Java 应用程序中为 API 方法定义响应信息。它是 Swagger 或 OpenAPI 规范的一部分，用于生成 API 文档。在包中，注解用于描述一个 API 操作的响应。它可以指定 HTTP 状态码、响应描述、响应内容等信息。源代码@Inherited。
swagger2注解说明
平常心丷的博客
03-11 515
@Api：用在请求的类上，表示对类的说明 tags="说明该类的作用，可以在UI界面上看到的注解" value="该参数没什么意义，在UI界面上也看到，所以不需要配置use case:@Api(tags="APP用户注册Controller") @ApiOperation：用在请求的方法上，说明方法的用途、作用 value="说明方法的用途、作用" notes="方法的备...
@ApiResponses
qq_42360413的博客
07-10 9364
@ApiResponses：用于表示一组响应 @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400 message：信息，例如”请求参数没填好” response：抛出异常的类
@ApiResponse & swagger 注解
weixin_45129599的博客
03-28 539
一些公司没有专业的开发文档，后台提供的Knife4j接口没有直接的展示结果，特此追加新的内动import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.T...
Swagger2注解：让API文档更智能
xycxycooo的博客
08-17 640
Swagger是一个用于生成、描述、调用和可视化RESTful Web服务的开放源代码框架。Swagger2是Swagger框架的一个版本，它通过注解的方式，让开发者可以轻松地在代码中定义API文档。通过本文的讲解，我们了解了Swagger2中常用的注解，包括@Api@ApiParam@ApiModel和。这些注解可以帮助我们在代码中直接定义API文档，使得文档与代码保持同步，减少维护成本，提高开发效率。
Swagger2 常用注解使用及其说明
li-shaoyu的博客
08-11 499
目录 Swagger2 常用注解使用及其说明 1、 Api 2、ApiModel 3、ApiModelProperty 4、ApiParam 5、ApiOperation 6、ApiResponse 和 ApiResponses 7、ApiImplicitParam 和 ApiImplicitParams Swagger2 常用注解使用及其说明 1、 Api @Api 用在类上，说明该类的作用。可以标记一个 Controller 类作为 Swagger 文档资源。 ...
Swagger（SpringBoot集成Swagger 常用Swagger注解）
qq_52897007的博客
07-31 4142
相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了发现了痛点就要去找解决方案。
Swagger中@ApiIgnore注解的使用详解
DN金猿的博客
01-21 337
由于架构革新，进入了前后端分离，服务端只需提供RESTful API的时代。而构建RESTful API会考虑到多终端的问题，这样就需要面对多个开发人员甚至多个开发团队。为了减少与其他团队对接的沟通成本，我们通常会写好对应的API接口文档。从最早开始的word文档，到后续的showdoc，都能减少很多沟通成本，但随之带来的问题也比较麻烦。在开发期间接口会因业务的变更频繁而变动，如果需要实时更新接口文档，这是一个费时费力的工作。为了解决上面的问题，Swagger应运而生。
@ApiResponses、@ApiResponse、@ApiImplicitParams、ApiImplicitParam
热门推荐
qq_36826506的博客
08-29 5万+
@ApiImplicitParam： 作用在方法上，表示单独的请求参数  参数：  1. name ：参数名。  2. value ： 参数的具体意义，作用。  3. required ： 参数是否必填。  4. dataType ：参数的数据类型。  5. paramType ：查询参数类型，这里有几种形式： 类型 作用 path 以地址的形式提交数据 query ...
Swagger学习⑯——@ApiResponses注解
一个写了10年bug的程序员日常笔记。
01-10 439
是 Swagger/OpenAPI 注解库中的一个注解，用于在 Java 应用程序中为 API 方法定义多个响应。它是注解的容器注解，允许你为一个 API 方法指定多个可能的响应。
swagger2注解学习@Api
WorldMvp的专栏
03-09 468
一、swagger简介 Swagger是目前最好用的Restful API文档生成的开源项目。通过swagger-spring项目，其实现了与SpingMVC框架的无缝集成功能，方便生成spring restful风格的接口文档。同时，swagger-ui还具有测试spring restful风格的接口的功能。 swagger官方网站为：http://swagger.io/ swagger中...
Swagger2.0@ApiResponse的response参数无效
小林同学的博客
11-27 3608
Swagger2.0@ApiResponse的response参数无效，查询了相关资料，说是因为Springfox3.0默认用swagger v3来返回信息，但有个地方又出毛病了。produces 属性，用来指定当前接口能够响应的媒体类型，也可以理解为此接口可以处理的媒体类型。（之后还使用 @ApiOperation(）添加response的方法进行尝试也是无效）大概意思是说如果没有设置媒体类型的话，将会导致该接口去忽略响应参数。所以接下就很简单了。今天在给swagger添加响应参数的时候发现无效。
swagger @Api @ApiOperation @ApiImplicitParams @ApiResponses @ApiModel @ApiModelProperty 基本使用总结
weixin_44131922的博客
07-27 4415
一般controller上@Api(value="标题",tags="标签一",description="描述")publicclassxxxxxxxxxxxController{@Api用在总的controller上方value即名称，也可以默认不写value，默认会给与value例如@Api("标题")tags即对api的分类，类似于接口的标签用于进一步分类description即对接口的描述一般接口上如下示例对当前具体接口的描述，......
swagger2 @ApiResponse的response不起作用
左直拳的马桶_日用桶
04-13 1万+
swagger可以生成比较友好的在线API说明文档。友好的API说明重要性不言而喻，因为所谓API，肯定就是被用来调用的，事关不同群体的工作，比如前端后端，本公司与第三方公司。以往，制订数据接口，要正正经经地写一份正式的文档，名曰集成规范。但现在有了swagger框架，就方便许多了，直接利用代码生成在线的接口说明文档。 不过最近在应用过程中遇到了一点问题。 Springfox 3.0 uses v3 models by default, but source.getResponses() gives wro
swagger注释API详细说明
2401_84002730的博客
04-12 924
一个人可以走的很快，但一群人才能走的更远。不论你是正从事IT行业的老鸟或是对IT行业感兴趣的新人，都欢迎扫码加入我们的的圈子（技术交流、学习资源、职场吐槽、大厂内推、面试辅导），让我们一起学习成长！中…(img-R84bzQx3-1712873154460)][外链图片转存中…(img-vYaAPdk0-1712873154461)]一个人可以走的很快，但一群人才能走的更远。
Swagger注解
最新发布
05-31
### Swagger注解的使用方法与示例 Swagger注解是用于描述API接口和参数的重要工具，它能够帮助开发者自动生成API文档[^1]。以下是关于如何使用Swagger注解以及一些常见的示例代码。 #### 1. 引入依赖 在使用Swagger注解之前，需要确保项目中已经引入了相关的依赖。例如，在Maven项目中可以添加以下依赖： ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> ``` #### 2. 配置Swagger 在Spring Boot项目中，可以通过配置类启用Swagger功能。以下是一个简单的配置示例： ```java @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) .paths(PathSelectors.any()) .build(); } } ``` #### 3. 使用常见注解 Swagger提供了多种注解来描述API接口及其参数。以下是一些常用的注解及其功能： - **@Api**：用于类上，描述该控制器的功能或模块名称。 ```java @Api(tags = "用户管理模块") ``` - **@ApiOperation**：用于方法上，描述接口的具体操作及说明。 ```java @ApiOperation(value = "获取用户信息", notes = "根据用户ID查询用户详细信息") ``` - **@ApiParam**：用于方法参数上，描述参数的作用及约束条件。 ```java @GetMapping("/user/{id}") public ResponseEntity<User> getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) { // 方法实现 } ``` - **@ApiResponse**：用于描述接口可能返回的响应结果。 ```java @ApiResponse(code = 404, message = "未找到指定资源") ``` - **@ApiModel** 和 **@ApiModelProperty**：用于描述复杂的对象模型。 ```java @ApiModel(description = "用户实体类") public class User { @ApiModelProperty(value = "用户ID", example = "1") private Long id; @ApiModelProperty(value = "用户名", example = "张三") private String name; } ``` #### 4. 示例代码 以下是一个完整的示例代码，展示了如何使用Swagger注解描述一个简单的API接口： ```java @RestController @RequestMapping("/api/user") @Api(tags = "用户管理模块", description = "提供用户相关操作的API接口") public class UserController { @ApiOperation(value = "创建用户", notes = "根据用户信息创建新用户") @PostMapping("/create") public ResponseEntity<String> createUser(@RequestBody @ApiParam(value = "用户信息") User user) { // 创建用户的逻辑 return ResponseEntity.ok("用户创建成功"); } @ApiOperation(value = "获取用户信息", notes = "根据用户ID查询用户详细信息") @ApiResponses({ @ApiResponse(code = 200, message = "成功返回用户信息"), @ApiResponse(code = 404, message = "未找到指定用户") }) @GetMapping("/get/{id}") public ResponseEntity<User> getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) { // 查询用户的逻辑 return ResponseEntity.ok(new User()); } } ``` #### 5. 注意事项 在使用Swagger注解时需要注意以下几点： - 确保注解的描述清晰、简洁且符合实际需求[^2]。 - 避免超出Swagger-UI页面可展示的字符限制（通常为120个字符以内）[^3]。 - 对于复杂的数据结构，建议使用`@ApiModel`和`@ApiModelProperty`进行详细描述。 ---
评论 4
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值