当前位置：首页 > article >正文

Swagger学习⑯——@ApiResponses注解

article 2025/1/11 23:51:04

介绍

@ApiResponses 是 Swagger/OpenAPI 注解库中的一个注解，用于在 Java 应用程序中为 API 方法定义多个响应。它是 @ApiResponse 注解的容器注解，允许你为一个 API 方法指定多个可能的响应。

基本用法

@ApiResponses 通常与 @ApiResponse 一起使用，用于描述一个 API 方法可能返回的不同 HTTP 状态码及其对应的响应信息。

源代码

package io.swagger.v3.oas.annotations.responses;

import io.swagger.v3.oas.annotations.extensions.Extension;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.METHOD, ElementType.TYPE, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface ApiResponses {
    ApiResponse[] value() default {};

    Extension[] extensions() default {};
}

注解属性

ApiResponse[] value() default {};:
这是 @ApiResponses 的主要属性，用于指定一组 @ApiResponse 注解。
- value() 是默认属性，可以省略属性名直接赋值。
- default {} 表示如果没有显式赋值，默认值为空数组。
Extension[] extensions() default {};:
这是 @ApiResponses 的扩展属性，用于支持 OpenAPI 规范的扩展功能。
- extensions() 是属性名，可以通过 extensions = {...} 的方式赋值。
- default {} 表示如果没有显式赋值，默认值为空数组。

示例代码

import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@ApiResponses(value = {
    @ApiResponse(
        responseCode = "200",
        description = "请求成功",
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(implementation = DemoResponse.class)
        )
    ),
    @ApiResponse(
        responseCode = "400",
        description = "请求参数错误",
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(implementation = ErrorResponse.class)
        )
    ),
    @ApiResponse(
        responseCode = "404",
        description = "资源未找到"
    )
})
public ResponseEntity<DemoResponse> getResource() {
    // 方法实现
}