| <!-- |
| /*************************************************************************************************************************** |
| * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations under the License. |
| ***************************************************************************************************************************/ |
| --> |
| |
| @ResponseHeader |
| |
| <p> |
| The {@link oaj.http.annotation.ResponseHeader @ResponseHeader} annotation can be applied to <ja>@RestMethod</ja>-annotated parameters to denote them as an HTTP response headers. |
| </p> |
| <ul class='javatree'> |
| <li class='ja'>{@link oaj.http.annotation.ResponseHeader} |
| <ul> |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#_default() _default} - Default value if not present. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#_enum() _enum} - Output validation. Must match one of the values. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#$ref() $ref} - Schema reference. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#api() api} - Free-form Swagger JSON. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#code() code} - HTTP status codes that this header applies to. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#collectionFormat() collectionFormat} - How collections of items are formatted. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#description() description} - Description. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#example() example} - Serialized example. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#exclusiveMaximum() exclusiveMaximum} - Output validation. Whether maximum is exclusive. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#exclusiveMinimum() exclusiveMinimum} - Output validation. Whether minimum is exclusive. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#format() format} - The schema type format. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#items() items} - The schema of items in a collection. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#maximum() maximum} - Output validation. Maximum numeric value. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#maxItems() maxItems} - Output validation. Maximum number of items in a collection. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#maxLength() maxLength} - Output validation. Maximum length of a string. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#minimum() minimum} - Output validation. Minimum numeric value. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#minItems() minItems} - Output validation. Minimum number of items in a collection. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#minLength() minLength} - Output validation. Minimum length of a string. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#multipleOf() multipleOf} - Output validation. Number must be a multiple of. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#name() name} - Header name. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#pattern() pattern} - Output validation. Must match regular expression. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#serializer() serializer} - Override the part serializer. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#type() type} - The schema type. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#uniqueItems() uniqueItems} - Output validation. Collections must contain unique items only. |
| <li class='jf'>{@link oaj.http.annotation.ResponseHeader#value() value} - Free-form Swagger JSON. |
| </ul> |
| </ul> |
| <p> |
| This annotation can only be applied to parameters of type {@link oaj.Value}. |
| </p> |
| <p> |
| The following examples show 3 different ways of accomplishing the same task of setting an HTTP header |
| on a response: |
| </p> |
| <p class='bpcode w800'> |
| <jc>// Example #1 - Setting header directly on RestResponse object.</jc> |
| <ja>@RestMethod</ja>(...) |
| <jk>public void</jk> login(RestResponse res) { |
| res.setHeader(<js>"X-Rate-Limit"</js>, 1000); |
| ... |
| } |
| |
| <jc>// Example #2 - Use on parameter.</jc> |
| <ja>@RestMethod</ja>(...) |
| <jk>public void</jk> login( |
| <ja>@ResponseHeader</ja>( |
| name=<js>"X-Rate-Limit"</js>, |
| type=<js>"integer"</js>, |
| format=<js>"int32"</js>, |
| description=<js>"Calls per hour allowed by the user."</js>, |
| example=<js>"123"</js> |
| ) |
| Value<Integer> rateLimit |
| ) |
| { |
| rateLimit.set(1000); |
| ... |
| } |
| |
| <jc>// Example #3 - Use on type.</jc> |
| <ja>@RestMethod</ja>(...) |
| <jk>public void</jk> login(Value<RateLimit> rateLimit) { |
| rateLimit.set(<jk>new</jk> RateLimit()); |
| ... |
| } |
| |
| <ja>@ResponseHeader</ja>( |
| name=<js>"X-Rate-Limit"</js>, |
| type=<js>"integer"</js>, |
| format=<js>"int32"</js>, |
| description=<js>"Calls per hour allowed by the user."</js>, |
| example=<js>"123"</js> |
| ) |
| <jk>public class</jk> RateLimit { |
| <jc>// OpenApiSerializer knows to look for this method based on format/type.</jc> |
| <jk>public</jk> Integer toInteger() { |
| <jk>return</jk> 1000; |
| } |
| } |
| </p> |
| |
| <h5 class='topic'>Swagger documentation</h5> |
| <p> |
| The attributes on this annotation are also used to populate the generated Swagger for the method. |
| For example, in the case of the <c>X-Rate-Limit</c> example above, the following Swagger is generated: |
| </p> |
| <p class='bpcode w800'> |
| <jok>'/user/login'</jok>: { |
| <jok>get</jok>: { |
| <jok>responses</jok>: { |
| <jok>200</jok>: { |
| <jok>headers</jok>: { |
| <jok>'X-Rate-Limit'</jok>: { |
| <jok>type</jok>: <jov>'integer'</jov>, |
| <jok>format</jok>: <jov>'int32'</jov>, |
| <jok>description</jok>: <jov>'Calls per hour allowed by the user.'</jov>, |
| <jok>example</jok>: <jov>'123'</jov> |
| } |
| } |
| } |
| } |
| } |
| } |
| </p> |
| |