@ResponseHeader
The {@link oaj.http.annotation.ResponseHeader @ResponseHeader} annotation can be applied to @RestMethod-annotated parameters to denote them as an HTTP response headers.
- {@link oaj.http.annotation.ResponseHeader}
- {@link oaj.http.annotation.ResponseHeader#_default() _default} - Default value if not present.
- {@link oaj.http.annotation.ResponseHeader#_enum() _enum} - Output validation. Must match one of the values.
- {@link oaj.http.annotation.ResponseHeader#$ref() $ref} - Schema reference.
- {@link oaj.http.annotation.ResponseHeader#api() api} - Free-form Swagger JSON.
- {@link oaj.http.annotation.ResponseHeader#code() code} - HTTP status codes that this header applies to.
- {@link oaj.http.annotation.ResponseHeader#collectionFormat() collectionFormat} - How collections of items are formatted.
- {@link oaj.http.annotation.ResponseHeader#description() description} - Description.
- {@link oaj.http.annotation.ResponseHeader#example() example} - Serialized example.
- {@link oaj.http.annotation.ResponseHeader#exclusiveMaximum() exclusiveMaximum} - Output validation. Whether maximum is exclusive.
- {@link oaj.http.annotation.ResponseHeader#exclusiveMinimum() exclusiveMinimum} - Output validation. Whether minimum is exclusive.
- {@link oaj.http.annotation.ResponseHeader#format() format} - The schema type format.
- {@link oaj.http.annotation.ResponseHeader#items() items} - The schema of items in a collection.
- {@link oaj.http.annotation.ResponseHeader#maximum() maximum} - Output validation. Maximum numeric value.
- {@link oaj.http.annotation.ResponseHeader#maxItems() maxItems} - Output validation. Maximum number of items in a collection.
- {@link oaj.http.annotation.ResponseHeader#maxLength() maxLength} - Output validation. Maximum length of a string.
- {@link oaj.http.annotation.ResponseHeader#minimum() minimum} - Output validation. Minimum numeric value.
- {@link oaj.http.annotation.ResponseHeader#minItems() minItems} - Output validation. Minimum number of items in a collection.
- {@link oaj.http.annotation.ResponseHeader#minLength() minLength} - Output validation. Minimum length of a string.
- {@link oaj.http.annotation.ResponseHeader#multipleOf() multipleOf} - Output validation. Number must be a multiple of.
- {@link oaj.http.annotation.ResponseHeader#name() name} - Header name.
- {@link oaj.http.annotation.ResponseHeader#pattern() pattern} - Output validation. Must match regular expression.
- {@link oaj.http.annotation.ResponseHeader#serializer() serializer} - Override the part serializer.
- {@link oaj.http.annotation.ResponseHeader#type() type} - The schema type.
- {@link oaj.http.annotation.ResponseHeader#uniqueItems() uniqueItems} - Output validation. Collections must contain unique items only.
- {@link oaj.http.annotation.ResponseHeader#value() value} - Free-form Swagger JSON.
This annotation can only be applied to parameters of type {@link oaj.Value}.
The following examples show 3 different ways of accomplishing the same task of setting an HTTP header
on a response:
// Example #1 - Setting header directly on RestResponse object.
@RestMethod(...)
public void login(RestResponse res) {
res.setHeader("X-Rate-Limit", 1000);
...
}
// Example #2 - Use on parameter.
@RestMethod(...)
public void login(
@ResponseHeader(
name="X-Rate-Limit",
type="integer",
format="int32",
description="Calls per hour allowed by the user.",
example="123"
)
Value<Integer> rateLimit
)
{
rateLimit.set(1000);
...
}
// Example #3 - Use on type.
@RestMethod(...)
public void login(Value<RateLimit> rateLimit) {
rateLimit.set(new RateLimit());
...
}
@ResponseHeader(
name="X-Rate-Limit",
type="integer",
format="int32",
description="Calls per hour allowed by the user.",
example="123"
)
public class RateLimit {
// OpenApiSerializer knows to look for this method based on format/type.
public Integer toInteger() {
return 1000;
}
}
Swagger documentation
The attributes on this annotation are also used to populate the generated Swagger for the method.
For example, in the case of the X-Rate-Limit example above, the following Swagger is generated:
'/user/login': {
get: {
responses: {
200: {
headers: {
'X-Rate-Limit': {
type: 'integer',
format: 'int32',
description: 'Calls per hour allowed by the user.',
example: '123'
}
}
}
}
}
}