介绍
@Header 是 Swagger/OpenAPI 3.0 注解中的一个注解，用于定义 API 响应或请求中的头部信息。它属于 io.swagger.v3.oas.annotations.headers 包，通常用于描述 HTTP 请求或响应中的自定义头部字段。
源代码
package io.swagger.v3.oas.annotations.headers;import io.swagger.v3.oas.annotations.media.Schema;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;@Target({})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface Header {String name();String description() default "";Schema schema() default @Schema;boolean required() default false;boolean deprecated() default false;String ref() default "";
}作用
@Header 注解用于定义 API 文档中的头部信息，包括头部的名称、描述、数据类型、示例值等。它可以帮助开发者和用户更好地理解 API 的请求或响应中使用的头部字段。
使用场景
-
当你的 API 需要在请求或响应中使用自定义头部字段时，可以使用
@Header注解来描述这些字段。 -
在生成的 OpenAPI 文档中，用户可以清楚地看到请求或响应中需要传递或返回的头部信息。
注解参数
@Header 注解支持以下参数：
| 参数名 | 类型 | 描述 |
|---|---|---|
name | String | 必填。头部的名称，例如 X-Custom-Header。 |
description | String | 可选。头部的描述信息，用于说明头部的用途。 |
schema | Schema | 必填。头部的数据类型和格式，使用 @Schema 注解定义。 |
required | boolean | 可选。指示头部是否是必需的，默认值为 false。 |
deprecated | boolean | 可选。指示头部是否已弃用，默认值为 false。 |
allowEmptyValue | boolean | 可选。指示头部是否允许空值，默认值为 false。 |
example | String | 可选。头部的示例值。 |
示例代码
在响应中使用 @Header
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.headers.Header;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.core.Response;@Path("/demo")
public class DemoResource {@GET@Path("/with-header")@Operation(summary = "获取带有自定义头部的响应",responses = {@ApiResponse(responseCode = "200",description = "成功响应",headers = {@Header(name = "X-Custom-Header",description = "自定义头部示例",schema = @Schema(type = "string", example = "custom-value"))})})public Response getWithHeader() {return Response.ok().header("X-Custom-Header", "custom-value").build();}
}在请求中使用 @Header
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.headers.Header;
import io.swagger.v3.oas.annotations.media.Schema;import javax.ws.rs.HeaderParam;
import javax.ws.rs.POST;
import javax.ws.rs.Path;@Path("/demo")
public class DemoResource {@POST@Path("/with-request-header")@Operation(summary = "接收带有自定义头部的请求",parameters = {@Parameter(name = "X-Custom-Header",description = "自定义请求头部",schema = @Schema(type = "string", example = "custom-value"),in = ParameterIn.HEADER)})public String postWithHeader(@HeaderParam("X-Custom-Header") String customHeader) {return "Received 自定义 header: " + customHeader;}
}
