org.apache.juneau.http.annotation.Path 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 path annotation.
*
*
* Identifies a POJO to be used as a path entry on 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 variable
* in a URL path pattern.
*
* Example:
*
* @RestMethod (name=GET , path="/myurl/{foo}/{bar}/{baz}/*" )
* public void doGet(
* @Path ("foo" ) String foo,
* @Path ("bar" ) int bar,
* @Path ("baz" ) UUID baz,
* @Path ("/*" ) String remainder,
* ) {...}
*
*
*
* The special name "/*" is used to retrieve the path remainder after the path match (i.e. the part that matches "/*" ).
*
*
See Also:
*
* - {@doc juneau-rest-server.HttpPartAnnotations.Path}
*
- {@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 path variables on the request.
*
* See Also:
*
* - {@doc juneau-rest-client.RestProxies.Path}
*
*
* 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 Path {
/**
* 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
//=================================================================================================================
/**
* URL path variable name.
*
*
* The path remainder after the path match can be referenced using the name "/*" .
*
The non-URL-decoded path remainder after the path match can be referenced using the name "/**" .
*
*
* The value should be either a valid path parameter 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 treated as name/value pairs.
*
* Examples:
*
* // When used on a REST method
* @RestMethod (path="/addPet" )
* public void addPet(@Path ObjectMap allPathParameters) {...}
*
*
* // When used on a remote method parameter
* @RemoteResource (path="/myproxy" )
* public interface MyProxy {
*
* // Equivalent to @Path("*")
* @RemoteMethod (path="/mymethod/{foo}/{bar}" )
* String myProxyMethod1(@Path Map<String,Object> allPathParameters);
* }
*
*
* // When used on a request bean method
* public interface MyRequest {
*
* // Equivalent to @Path("*")
* @Path
* Map<String,Object> getPathVars();
* }
*
*
* -
* If used on a request bean method, uses the bean property name.
*
*
Example:
*
* public interface MyRequest {
*
* // Equivalent to @Path("foo")
* @Path
* String getFoo();
* }
*
*
*
* The name field MUST correspond to the associated {@doc SwaggerPathsPath path} segment from the path field in the {@doc SwaggerPathsObject Paths Object}.
* See {@doc SwaggerPathTemplating Path Templating} for further information.
*
*
Notes:
*
* -
* The format is plain-text.
*
*/
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 path entry:
*
* @RestMethod (
* name="GET" ,
* path="/pet/{petId}"
* )
* public Pet getPet(@Path (name="petId" ) long petId) { ... }
*
*
* @RestMethod (
* name="GET" ,
* path="/pet/{petId}"
* )
* public Pet getPet(@Path ("petId" ) long petId) { ... }
*
*/
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 {};
//=================================================================================================================
// 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 path parameter 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}.
*
*
* Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements.
*
*
Used for:
*
* -
* Server-side schema-based parsing.
*
-
* Server-side generated Swagger documentation.
*
-
* Client-side schema-based serializing.
*
*/
String collectionFormat() 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
* @RestMethod (name="GET" , path="/pet/findByStatus/{status}" )
* public Collection<Pet> findPetsByStatus(
* @Path (
* name="status" ,
* _enum="AVAILABLE,PENDING,SOLD" ,
* ) PetStatus status
* ) {...}
*
*
* // JSON array
* @RestMethod (name="GET" , path="/pet/findByStatus/{status}" )
* public Collection<Pet> findPetsByStatus(
* @Path (
* name="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:
*
* @Path (
* 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 {@doc juneau-marshall.JsonDetails.SimplifiedJson} object that makes up the swagger information for this field.
*
*
* The following are completely equivalent ways of defining the swagger description of the Path object:
*
* // Normal
* @Path (
* name="orderId" ,
* description="ID of order to fetch" ,
* maximum="1000" ,
* minimum="101" ,
* example="123"
* )
*
*
* // Free-form
* @Path ({
* name="orderId" ,
* api={
* "description: 'ID of order to fetch'," ,
* "maximum: 1000," ,
* "minimum: 101," ,
* "example: 123"
* }
* )
*
*
* // Free-form using variables
* @Path ({
* name="orderId" ,
* api="$L{orderIdSwagger}"
* )
*
*
* // Contents of MyResource.properties
* orderIdSwagger = { description: "ID of order to fetch", maximum: 1000, minimum: 101, example: 123 }
*
*
*
* 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:
*
* @Path (api="{description: 'ID of order to fetch'}" )
*
*
* @Path (api="description: 'ID of order to fetch''" )
*
* -
* 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 {};
}