Swagger 注解 @ApiResponses 和 @ApiResponse 的用法

@ApiResponses 和 @ApiResponse 是 Swagger 提供的两个注解，用于定义 API 接口的响应信息，包括状态码、描述信息等。它们可以更好地描述和说明 API 接口的返回结果，提供更清晰、准确的文档和信息。

@ApiResponses 和 @ApiResponse 使用场景

使用 @ApiResponses 注解可以在 API 接口中定义不同响应状态码的描述信息，帮助开发人员和使用者更好地了解接口的返回结果。它们在以下场景下特别有意义：

• 定义不同的成功或失败的响应状态码和描述信息；
• 描述异常或错误情况下的响应信息；
• 提供多种情况下的响应示例。
  

@ApiResponses 和 @ApiResponse 用法介绍

下面是 @ApiResponses 和 @ApiResponse 注解的用法介绍：

@ApiResponses 注解的属性：

@ApiResponse 注解的属性：

实践案例

假设我们有一个基于 Spring Boot 的用户管理系统，我们将演示如何在该项目中使用 @ApiResponses 和 @ApiResponse 注解来定义 API 接口的响应信息。首先，我们需要添加相关依赖到项目的 pom.xml 文件中：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

接下来，创建一个 UserController 类，定义一个获取所有用户信息的 API 接口：

@RestController
@RequestMapping("/api")
@Api(value = "User API")
public class UserController {

    @GetMapping("/users")
    @ApiOperation(value = "获取所有用户信息")
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "成功", response = User.class, reference = "https://example.com/users"),
        @ApiResponse(code = 404, message = "未找到用户"),
        @ApiResponse(code = 500, message = "服务器内部错误")
    })
    public List<User> getUsers() {
        // 获取并返回所有用户信息
    }
}

在上面的示例代码中，我们使用了 @ApiResponses 注解来定义不同响应状态码的描述信息，并使用了 @ApiResponse 注解来定义每个具体的响应。
其中，@ApiResponse 注解的属性包括：

• code：表示响应的状态码；
• message：表示响应的描述信息；
• response：表示返回的数据类型，这里我们使用了 User.class；
• reference：表示响应的参考文档链接，这里我们假设为"https://example.com/users"。

启动应用程序，在浏览器中访问 http://localhost:8080/swagger-ui/index.html ，即可看到 Swagger UI 页面。

在 Swagger UI 页面中，展开 "User API" 下的 "GET /api/users" 接口，可以看到该接口的详细信息，包括请求方式、路径、响应等。

注意事项

在使用 @ApiResponses 和 @ApiResponse 注解时，需要注意以下事项：

• 状态码应遵循 HTTP 标准的状态码定义；
• 描述信息应准确、简洁，能够清晰地表达响应的含义；
• 对于具体的响应数据类型，应根据实际情况进行设置。
  
  

常见的问题与解决方法

为什么我在 Swagger UI 中看不到 API 的响应描述？

确保你已正确使用了 @ApiResponses 和 @ApiResponse 注解，并设置了正确的状态码和描述信息。检查 Swagger 配置文件中是否启用了 API 文档生成的相关配置。

如何在 Swagger UI 中查看响应示例？

确保你在 @ApiResponse 注解中设置了正确的响应实体类。检查 Swagger 配置文件中是否启用了生成示例代码的相关配置。

Swagger 和 Apifox 整合

Swagger 管理接口有时很不方便，缺乏一定的安全性和团队间的分享协作，所以我更推荐使用 Apifox 的 IDEA 插件。你可以在 IDEA 中自动同步 Swagger 注解到 Apifox，一键生成接口文档，多端同步，非常方便测试和维护，这样就可以迅速分享 API 给其他小伙伴。

Apifox 是一个比 Postman 更强大的接口测试工具，Apifox = Postman + Swagger + Mock + JMeter，Apifox 支持调试 http（s）、WebSocket、Socket、gRPC、Dubbo 等协议的接口，并且集成了 IDEA 插件。

Apifox 的 IDEA 插件可以自动解析代码注释，并基于 Javadoc、KDoc 和 ScalaDoc 生成 API 文档。通过 IntelliJ IDEA 的 Apifox Helper 插件，开发人员可以在不切换工具的情况下将他们的文档与 Apifox 项目同步。

当在 IDEA 项目中有接口信息变动，只需右键点击「 Upload to Apifox」一键即可完成同步，无需奔走相告。团队成员可在 Apifox 中看到同步后的最新内容。

现在出发去 JetBrains 插件市场 下载试试吧！或直接在 IDEA 内 「plugin」入口直接搜索 Apifox Helper。

知识扩展：

• Swagger 注解 @ApiImplicitParams 和 @ApiImplicitParam 的用法
• Swagger 注解 @ApiParam 的用法

参考链接：

• Swagger 官方文档：https://swagger.io/docs/
• SpringFox 文档：https://springfox.github.io/springfox/docs/current/