• Home
• org.apache.juneau
• juneau-all
• 7.2.0
• source code
• Header.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

org.apache.juneau.http.annotation.Header Maven / Gradle / Ivy

// ***************************************************************************************************************************
// * 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.                                              *
// ***************************************************************************************************************************
package org.apache.juneau.http.annotation;

import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;

import java.lang.annotation.*;
import java.util.*;

import org.apache.juneau.*;
import org.apache.juneau.annotation.*;
import org.apache.juneau.httppart.*;
import org.apache.juneau.json.*;
import org.apache.juneau.jsonschema.*;
import org.apache.juneau.oapi.*;

/**
 * REST request header annotation.
 *
 * 

 * Identifies a POJO to be used as the header of an HTTP request.
 *
 * 

 * Can be used in the following locations:
 * 

 * 	
Arguments and argument-types of server-side @RestMethod-annotated methods.
 * 	
Arguments and argument-types of client-side @RemoteResource-annotated interfaces.
 * 	
Methods and return types of server-side and client-side @Request-annotated interfaces.
 * 
 *
 * 
Arguments and argument-types of server-side @RestMethod-annotated methods
 *
 * Annotation that can be applied to a parameter of a @RestMethod-annotated method to identify it as a HTTP
 * request header.
 *
 * 
Example:
 * 

 * 	@RestMethod(name=GET)
 * 	public void doGet(@Header("ETag") UUID etag) {...}
 * 
 *
 * 

 * This is functionally equivalent to the following code...
 * 

 * 	@RestMethod(name=GET)
 * 	public void doPostPerson(RestRequest req, RestResponse res) {
 * 		UUID etag = req.getHeader(UUID.class, "ETag");
 * 		...
 * 	}
 * 
 *
 * 
See Also:
 * 

 * 	
{@doc juneau-rest-server.HttpPartAnnotations.Header}
 * 	
{@doc juneau-rest-server.Swagger}
 * 	
{@doc SwaggerParameterObject}
 * 
 *
 * 
Arguments and argument-types of client-side @RemoteResource-annotated interfaces
 *
 * Annotation applied to Java method arguments of interface proxies to denote that they are serialized as an HTTP
 * header value.
 *
 * 
See Also:
 * 

 * 	
{@doc juneau-rest-client.RestProxies.Header}
 * 
 *
 * 
Methods and return types of server-side and client-side @Request-annotated interfaces
 *
 * 
See Also:
 * 

 * 	
{@doc juneau-rest-server.HttpPartAnnotations.Request}
 * 	
{@doc juneau-rest-client.RestProxies.Request}
 * 
 */
@Documented
@Target({PARAMETER,FIELD,METHOD,TYPE})
@Retention(RUNTIME)
@Inherited
public @interface Header {

	/**
	 * Skips this value during serialization if it's an empty string or empty collection/array.
	 *
	 * 

	 * Note that null values are already ignored.
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Client-side schema-based serializing.
	 * 
	 */
	boolean skipIfEmpty() default false;

	/**
	 * Specifies the {@link HttpPartSerializer} class used for serializing values to strings.
	 *
	 * 

	 * Overrides for this part the part serializer defined on the REST client which by default is {@link OpenApiSerializer}.
	 */
	Class serializer() default HttpPartSerializer.Null.class;

	/**
	 * Specifies the {@link HttpPartParser} class used for parsing strings to values.
	 *
	 * 

	 * Overrides for this part the part parser defined on the REST resource which by default is {@link OpenApiParser}.
	 */
	Class parser() default HttpPartParser.Null.class;

	//=================================================================================================================
	// Attributes common to all Swagger Parameter objects
	//=================================================================================================================

	/**
	 * HTTP header name.
	 * 

	 * A blank value (the default) indicates to reuse the bean property name when used on a request bean property.
	 *
	 * 

	 * The value should be either a valid HTTP header name, or "*" to represent multiple name/value pairs
	 *
	 * 

	 * A blank value (the default) has the following behavior:
	 * 

	 * 	

	 * 		If the data type is NameValuePairs, Map, or a bean,
	 * 		then it's the equivalent to "*" which will cause the value to be serialized as name/value pairs.
	 *
	 * 		
Examples:
	 * 		

	 * 	// When used on a REST method
	 * 	@RestMethod(path="/addPet")
	 * 	public void addPet(@Header ObjectMap allHeaderParameters) {...}
	 * 		
	 * 		

	 * 	// When used on a remote method parameter
	 * 	@RemoteResource(path="/myproxy")
	 * 	public interface MyProxy {
	 *
	 * 		// Equivalent to @Header("*")
	 * 		@RemoteMethod(path="/mymethod")
	 * 		String myProxyMethod1(@Header Map<String,Object> allHeaderParameters);
	 * 	}
	 * 		
	 * 		

	 * 	// When used on a request bean method
	 * 	public interface MyRequest {
	 *
	 * 		// Equivalent to @Header("*")
	 * 		@Header
	 * 		Map<String,Object> getFoo();
	 * 	}
	 * 		
	 * 	
	 * 	

	 * 		If used on a request bean method, uses the bean property name.
	 *
	 * 		
Example:
	 * 		

	 * 	public interface MyRequest {
	 *
	 * 		// Equivalent to @Header("Foo")
	 * 		@Header
	 * 		@BeanProperty("Foo")
	 * 		String getFoo();
	 * 	}
	 * 		
	 * 	
	 * 
	 */
	String name() default "";

	/**
	 * A synonym for {@link #name()}.
	 *
	 * 

	 * Allows you to use shortened notation if you're only specifying the name.
	 *
	 * 

	 * The following are completely equivalent ways of defining a header entry:
	 * 

	 * 	public Order placeOrder(@Header(name="api_key") String apiKey) {...}
	 * 
	 * 

	 * 	public Order placeOrder(@Header("api_key") String apiKey) {...}
	 * 
	 */
	String value() default "";

	/**
	 * description field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * A brief description of the parameter. This could contain examples of use.
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 
	 *
	 * 
Notes:
	 * 

	 * 	

	 * 		The format is plain text.
	 * 		
Multiple lines are concatenated with newlines.
	 * 	

	 * 		Supports {@doc DefaultRestSvlVariables}
	 * 		(e.g. "$L{my.localized.variable}").
	 * 
	 */
	String[] description() default {};

	/**
	 * required field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * Determines whether the parameter is mandatory.
	 *
	 * 

	 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
	 * 
On the client-side, this gets converted to a RestCallException which is thrown before the connection is made.
	 * 
On the server-side, this gets converted to a BadRequest (400).
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing validation.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing validation.
	 * 
	 */
	boolean required() default false;

	//=================================================================================================================
	// Attributes specific to parameters other than body
	//=================================================================================================================

	/**
	 * type field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * The type of the parameter.
	 *
	 * 

	 * The possible values are:
	 * 

	 * 	

	 * 		"string"
	 * 		
Parameter must be a string or a POJO convertible from a string.
	 * 	

	 * 		"number"
	 * 		
Parameter must be a number primitive or number object.
	 * 		
If parameter is Object, creates either a Float or Double depending on the size of the number.
	 * 	

	 * 		"integer"
	 * 		
Parameter must be a integer/long primitive or integer/long object.
	 * 		
If parameter is Object, creates either a Short, Integer, or Long depending on the size of the number.
	 * 	

	 * 		"boolean"
	 * 		
Parameter must be a boolean primitive or object.
	 * 	

	 * 		"array"
	 * 		
Parameter must be an array or collection.
	 * 		
Elements must be strings or POJOs convertible from strings.
	 * 		
If parameter is Object, creates an {@link ObjectList}.
	 * 	

	 * 		"object"
	 * 		
Parameter must be a map or bean.
	 * 		
If parameter is Object, creates an {@link ObjectMap}.
	 * 		
Note that this is an extension of the OpenAPI schema as Juneau allows for arbitrarily-complex POJOs to be serialized as HTTP parts.
	 * 	

	 * 		"file"
	 * 		
This type is currently not supported.
	 * 
	 *
	 * 

	 * Static strings are defined in {@link ParameterType}.
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing.
	 * 
	 *
	 * 
See Also:
	 * 

	 * 	
{@doc SwaggerDataTypes}
	 * 
	 */
	String type() default "";

	/**
	 * format field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * The extending format for the previously mentioned {@doc SwaggerParameterTypes parameter type}.
	 *
	 * 

	 * The possible values are:
	 * 

	 * 	

	 * 		"int32" - Signed 32 bits.
	 * 		
Only valid with type "integer".
	 * 	

	 * 		"int64" - Signed 64 bits.
	 * 		
Only valid with type "integer".
	 * 	

	 * 		"float" - 32-bit floating point number.
	 * 		
Only valid with type "number".
	 * 	

	 * 		"double" - 64-bit floating point number.
	 * 		
Only valid with type "number".
	 * 	

	 * 		"byte" - BASE-64 encoded characters.
	 * 		
Only valid with type "string".
	 * 		
Parameters of type POJO convertible from string are converted after the string has been decoded.
	 * 	

	 * 		"binary" - Hexadecimal encoded octets (e.g. "00FF").
	 * 		
Only valid with type "string".
	 * 		
Parameters of type POJO convertible from string are converted after the string has been decoded.
	 * 	

	 * 		"date" - An RFC3339 full-date.
	 * 		
Only valid with type "string".
	 * 	

	 * 		"date-time" - An RFC3339 date-time.
	 * 		
Only valid with type "string".
	 * 	

	 * 		"password" - Used to hint UIs the input needs to be obscured.
	 * 		
This format does not affect the serialization or parsing of the parameter.
	 * 	

	 * 		"uon" - UON notation (e.g. "(foo=bar,baz=@(qux,123))").
	 * 		
Only valid with type "object".
	 * 		
If not specified, then the input is interpreted as plain-text and is converted to a POJO directly.
	 * 
	 *
	 * 

	 * Static strings are defined in {@link FormatType}.
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing.
	 * 
	 *
	 * 
See Also:
	 * 

	 * 	
{@doc SwaggerDataTypeFormats}
	 * 
	 */
	String format() default "";


	/**
	 * allowEmptyValue field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * Sets the ability to pass empty-valued heaver values.
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing validation.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing validation.
	 * 
	 *
	 * 

	 * Note:  This is technically only valid for either query or formData parameters, but support is provided anyway for backwards compatability.
	 */
	boolean allowEmptyValue() default false;

	/**
	 * items field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * Describes the type of items in the array.
	 *
	 * 

	 * Required if type is "array".
	 * 
Can only be used if type is "array".
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing and parsing validation.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing and serializing validation.
	 * 
	 */
	Items items() default @Items;

	/**
	 * collectionFormat field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * Determines the format of the array if type "array" is used.
	 * 
Can only be used if type is "array".
	 *
	 * 
Possible values are:
	 * 

	 * 	

	 * 		"csv" (default) - Comma-separated values (e.g. "foo,bar").
	 * 	

	 * 		"ssv" - Space-separated values (e.g. "foo bar").
	 * 	

	 * 		"tsv" - Tab-separated values (e.g. "foo\tbar").
	 * 	

	 * 		"pipes - Pipe-separated values (e.g. "foo|bar").
	 * 	

	 * 		"uon" - UON notation (e.g. "@(foo,bar)").
	 * 	

	 * 
	 *
	 * 

	 * Static strings are defined in {@link CollectionFormatType}.
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing.
	 * 
	 *
	 * 

	 * Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements.
	 */
	String collectionFormat() default "";

	/**
	 * default field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request.
	 * 
(Note: "default" has no meaning for required parameters.)
	 *
	 * 

	 * Additionally, this value is used to create instances of POJOs that are then serialized as language-specific examples in the generated Swagger documentation
	 * if the examples are not defined in some other way.
	 *
	 * 

	 * The format of this value is a string.
	 * 
Multiple lines are concatenated with newlines.
	 *
	 * 
Examples:
	 * 

	 * 	public Order placeOrder(
	 * 		@Header(name="X-PetId", _default="100") long petId,
	 * 		@Header(name="X-AdditionalInfo", format="uon", _default="(rushOrder=false)") AdditionalInfo additionalInfo,
	 * 		@Header(name="X-Flags", collectionFormat="uon", _default="@(new-customer)") String[] flags
	 * 	) {...}
	 * 
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing.
	 * 
	 */
	String[] _default() default {};

	/**
	 * maximum field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * Defines the maximum value for a parameter of numeric types.
	 * 
The value must be a valid JSON number.
	 *
	 * 

	 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
	 * 
On the client-side, this gets converted to a RestCallException which is thrown before the connection is made.
	 * 
On the server-side, this gets converted to a BadRequest (400).
	 *
	 * 

	 * Only allowed for the following types: "integer", "number".
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing validation.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing validation.
	 * 
	 */
	String maximum() default "";

	/**
	 * exclusiveMaximum field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * Defines whether the maximum is matched exclusively.
	 *
	 * 

	 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
	 * 
On the client-side, this gets converted to a RestCallException which is thrown before the connection is made.
	 * 
On the server-side, this gets converted to a BadRequest (400).
	 *
	 * 

	 * Only allowed for the following types: "integer", "number".
	 * 
If true, must be accompanied with maximum.
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing validation.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing validation.
	 * 
	 */
	boolean exclusiveMaximum() default false;

	/**
	 * minimum field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * Defines the minimum value for a parameter of numeric types.
	 * 
The value must be a valid JSON number.
	 *
	 * 

	 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
	 * 
On the client-side, this gets converted to a RestCallException which is thrown before the connection is made.
	 * 
On the server-side, this gets converted to a BadRequest (400).
	 *
	 * 

	 * Only allowed for the following types: "integer", "number".
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing validation.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing validation.
	 * 
	 */
	String minimum() default "";

	/**
	 * exclusiveMinimum field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * Defines whether the minimum is matched exclusively.
	 *
	 * 

	 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
	 * 
On the client-side, this gets converted to a RestCallException which is thrown before the connection is made.
	 * 
On the server-side, this gets converted to a BadRequest (400).
	 *
	 * 

	 * Only allowed for the following types: "integer", "number".
	 * 
If true, must be accompanied with minimum.
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing validation.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing validation.
	 * 
	 */
	boolean exclusiveMinimum() default false;

	/**
	 * maxLength field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * A string instance is valid against this keyword if its length is less than, or equal to, the value of this keyword.
	 * 
The length of a string instance is defined as the number of its characters as defined by RFC 4627.
	 * 
The value -1 is always ignored.
	 *
	 * 

	 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
	 * 
On the client-side, this gets converted to a RestCallException which is thrown before the connection is made.
	 * 
On the server-side, this gets converted to a BadRequest (400).
	 *
	 * 

	 * Only allowed for the following types: "string".
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing validation.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing validation.
	 * 
	 */
	long maxLength() default -1;

	/**
	 * minLength field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * A string instance is valid against this keyword if its length is greater than, or equal to, the value of this keyword.
	 * 
The length of a string instance is defined as the number of its characters as defined by RFC 4627.
	 * 
The value -1 is always ignored.
	 *
	 * 

	 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
	 * 
On the client-side, this gets converted to a RestCallException which is thrown before the connection is made.
	 * 
On the server-side, this gets converted to a BadRequest (400).
	 *
	 * 

	 * Only allowed for the following types: "string".
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing validation.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing validation.
	 * 
	 */
	long minLength() default -1;

	/**
	 * pattern field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * A string input is valid if it matches the specified regular expression pattern.
	 *
	 * 

	 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
	 * 
On the client-side, this gets converted to a RestCallException which is thrown before the connection is made.
	 * 
On the server-side, this gets converted to a BadRequest (400).
	 *
	 * 

	 * Only allowed for the following types: "string".
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing validation.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing validation.
	 * 
	 */
	String pattern() default "";

	/**
	 * maxItems field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * An array or collection is valid if its size is less than, or equal to, the value of this keyword.
	 *
	 * 

	 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
	 * 
On the client-side, this gets converted to a RestCallException which is thrown before the connection is made.
	 * 
On the server-side, this gets converted to a BadRequest (400).
	 *
	 * 

	 * Only allowed for the following types: "array".
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing validation.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing validation.
	 * 
	 */
	long maxItems() default -1;

	/**
	 * minItems field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * An array or collection is valid if its size is greater than, or equal to, the value of this keyword.
	 *
	 * 

	 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
	 * 
On the client-side, this gets converted to a RestCallException which is thrown before the connection is made.
	 * 
On the server-side, this gets converted to a BadRequest (400).
	 *
	 * 

	 * Only allowed for the following types: "array".
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing validation.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing validation.
	 * 
	 */
	long minItems() default -1;

	/**
	 * uniqueItems field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * If true the input validates successfully if all of its elements are unique.
	 *
	 * 

	 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
	 * 
On the client-side, this gets converted to a RestCallException which is thrown before the connection is made.
	 * 
On the server-side, this gets converted to a BadRequest (400).
	 *
	 * 

	 * If the parameter type is a subclass of {@link Set}, this validation is skipped (since a set can only contain unique items anyway).
	 * 
Otherwise, the collection or array is checked for duplicate items.
	 *
	 * 

	 * Only allowed for the following types: "array".
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing validation.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing validation.
	 * 
	 */
	boolean uniqueItems() default false;

	/**
	 * enum field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * If specified, the input validates successfully if it is equal to one of the elements in this array.
	 *
	 * 

	 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
	 * 
On the client-side, this gets converted to a RestCallException which is thrown before the connection is made.
	 * 
On the server-side, this gets converted to a BadRequest (400).
	 *
	 * 

	 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} array or comma-delimited list.
	 * 
Multiple lines are concatenated with newlines.
	 *
	 * 
Examples:
	 * 

	 * 	// Comma-delimited list
	 * 	public Collection<Pet> findPetsByStatus(
	 * 		@Header(
	 * 			name="X-Status",
	 * 			_enum="AVAILABLE,PENDING,SOLD",
	 * 		) PetStatus status
	 * 	) {...}
	 * 
	 * 

	 * 	// JSON array
	 * 	public Collection<Pet> findPetsByStatus(
	 * 		@Header(
	 * 			name="X-Status",
	 * 			_enum="['AVAILABLE','PENDING','SOLD']",
	 * 		) PetStatus status
	 * 	) {...}
	 * 
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing validation.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing validation.
	 * 
	 */
	String[] _enum() default {};

	/**
	 * multipleOf field of the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * A numeric instance is valid if the result of the division of the instance by this keyword's value is an integer.
	 * 
The value must be a valid JSON number.
	 *
	 * 

	 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
	 * 
On the client-side, this gets converted to a RestCallException which is thrown before the connection is made.
	 * 
On the server-side, this gets converted to a BadRequest (400).
	 *
	 * 

	 * Only allowed for the following types: "integer", "number".
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side schema-based parsing validation.
	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 	

	 * 		Client-side schema-based serializing validation.
	 * 
	 */
	String multipleOf() default "";

	//=================================================================================================================
	// Other
	//=================================================================================================================

	/**
	 * A serialized example of the parameter.
	 *
	 * 

	 * This attribute defines a representation of the value that is used by BasicRestInfoProvider to construct
	 * an example of parameter.
	 *
	 * 
Example:
	 * 

	 * 	@Header(
	 * 		name="Status",
	 * 		type="array",
	 * 		collectionFormat="csv",
	 * 		example="AVALIABLE,PENDING"
	 * 	)
	 * 	PetStatus[] status
	 * 
	 *
	 * 

	 * If not specified, Juneau will automatically create examples from sample POJOs serialized using the registered {@link HttpPartSerializer}.
	 * 

	 *
	 * 
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 
	 *
	 * 
See also:
	 * 

	 * 	
{@link Example}
	 * 	
{@link BeanContext}
	 * 	

	 * 		
{@link BeanContext#BEAN_examples BEAN_examples}
	 * 	
	 * 	
{@link JsonSchemaSerializer}
	 * 	

	 * 		
{@link JsonSchemaGenerator#JSONSCHEMA_addExamplesTo JSONSCHEMA_addExamplesTo}
	 * 		
{@link JsonSchemaGenerator#JSONSCHEMA_allowNestedExamples JSONSCHEMA_allowNestedExamples}
	 * 	
	 * 
	 *
	 * 
Notes:
	 * 

	 * 	

	 * 		The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object or plain text string.
	 * 		
Multiple lines are concatenated with newlines.
	 * 	

	 * 		Supports {@doc DefaultRestSvlVariables}
	 * 		(e.g. "$L{my.localized.variable}").
	 * 
	 */
	String[] example() default {};

	/**
	 * Free-form value for the {@doc SwaggerParameterObject}.
	 *
	 * 

	 * This is a JSON object that makes up the swagger information for this field.
	 *
	 * 

	 * The following are completely equivalent ways of defining the swagger description of the request header:
	 * 

	 * 	// Normal
	 * 	@Header(
	 * 		name="api_key",
	 * 		description="Security API key",
	 * 		required=true,
	 * 		example="foobar"
	 * 	)
	 * 
	 * 

	 * 	// Free-form
	 * 	@Header(
	 * 		name="api_key",
	 * 		api={
	 * 			"description: 'Security API key',",
	 * 			"required: true,",
	 * 			"example: 'foobar'"
	 * 		}
	 * 	)
	 * 
	 * 

	 * 	// Free-form with variables
	 * 	@Header(
	 * 		name="api_key",
	 * 		api="$L{apiKeySwagger}"
	 * 	)
	 * 
	 * 

	 * 	// Contents of MyResource.properties
	 * 	apiKeySwagger = { description: "Security API key", required: true, example: "foobar" }
	 * 
	 *
	 * 

	 * 	The reasons why you may want to use this field include:
	 * 

	 * 	
You want to pull in the entire Swagger JSON definition for this field from an external source such as a properties file.
	 * 	
You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification.
	 * 
	 *
	 * 
Used for:
	 * 

	 * 	

	 * 		Server-side generated Swagger documentation.
	 * 
	 *
	 * 
Notes:
	 * 

	 * 	

	 * 		Note that the only swagger field you can't specify using this value is "name" whose value needs to be known during servlet initialization.
	 * 	

	 * 		The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
	 * 	

	 * 		Automatic validation is NOT performed on input based on attributes in this value.
	 * 	

	 * 		The leading/trailing { } characters are optional.
	 * 		
The following two example are considered equivalent:
	 * 		

	 * 	@Header(api="{required: true}")
	 * 		
	 * 		

	 * 	@Header(api="required: true")
	 * 		
	 * 	

	 * 		Multiple lines are concatenated with newlines so that you can format the value to be readable.
	 * 	

	 * 		Supports {@doc DefaultRestSvlVariables}
	 * 		(e.g. "$L{my.localized.variable}").
	 * 	

	 * 		Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation.
	 * 
	 */
	String[] api() default {};
}