@ResponseHeader

The {@link oaj.http.annotation.ResponseHeader @ResponseHeader} annotation can be applied to @RestMethod-annotated parameters to denote them as an HTTP response headers.

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