Swagger学习⑮——@ApiResponse注解

介绍

@ApiResponse 是 Swagger 注解库中的一个注解，用于在 Java 应用程序中为 API 方法定义响应信息。它是 Swagger 或 OpenAPI 规范的一部分，用于生成 API 文档。

在 io.swagger.v3.oas.annotations.responses 包中，@ApiResponse 注解用于描述一个 API 操作的响应。它可以指定 HTTP 状态码、响应描述、响应内容等信息。

源代码

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

import io.swagger.v3.oas.annotations.extensions.Extension;
import io.swagger.v3.oas.annotations.headers.Header;
import io.swagger.v3.oas.annotations.links.Link;
import io.swagger.v3.oas.annotations.media.Content;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Repeatable;
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
@Repeatable(ApiResponses.class)
public @interface ApiResponse {
    String description() default "";

    String responseCode() default "default";

    Header[] headers() default {};

    Link[] links() default {};

    Content[] content() default {};

    Extension[] extensions() default {};

    String ref() default "";

    boolean useReturnTypeSchema() default false;
}

参数说明

• responseCode: HTTP 状态码（例如 "200"、"400" 等）。

• description: 响应的描述信息。

• content: 响应的内容类型和结构（可选），可以通过 @Content 注解进一步定义。

• headers: 响应头信息（可选），可以通过 @Header 注解定义。

• links: 与其他操作的关联（可选），可以通过 @Link 注解定义。

示例代码

import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;

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