@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' } } } } } }