The {@link oaj.http.annotation.Path @Path} annotation is used to retrieve request path parameters.

• {@link oaj.http.annotation.Path Path}
  • {@link oaj.http.annotation.Path#_enum() _enum} - Input validation. Must match one of the values.
  • {@link oaj.http.annotation.Path#allowEmptyValue() allowEmptyValue} - Input validation. Allow empty value.
  • {@link oaj.http.annotation.Path#api() api} - Free-form Swagger JSON.
  • {@link oaj.http.annotation.Path#collectionFormat() collectionFormat} - How collections of items are formatted.
  • {@link oaj.http.annotation.Path#description() description} - Description.
  • {@link oaj.http.annotation.Path#example() example} - Serialized example.
  • {@link oaj.http.annotation.Path#exclusiveMaximum() exclusiveMaximum} - Input validation. Whether maximum is exclusive.
  • {@link oaj.http.annotation.Path#exclusiveMinimum() exclusiveMinimum} - Input validation. Whether minimum is exclusive.
  • {@link oaj.http.annotation.Path#format() format} - The schema type format.
  • {@link oaj.http.annotation.Path#items() items} - The schema of items in a collection.
  • {@link oaj.http.annotation.Path#maximum() maximum} - Input validation. Maximum numeric value.
  • {@link oaj.http.annotation.Path#maxLength() maxLength} - Input validation. Maximum length of a string.
  • {@link oaj.http.annotation.Path#minimum() minimum} - Input validation. Minimum numeric value.
  • {@link oaj.http.annotation.Path#minLength() minLength} - Input validation. Minimum length of a string.
  • {@link oaj.http.annotation.Path#multipleOf() multipleOf} - Input validation. Number must be a multiple of.
  • {@link oaj.http.annotation.Path#name() name} - Path variable name.
  • {@link oaj.http.annotation.Path#parser() parser} - Override the part parser.
  • {@link oaj.http.annotation.Path#pattern() pattern} - Input validation. Must match regular expression.
  • {@link oaj.http.annotation.Path#type() type} - The schema type.
  • {@link oaj.http.annotation.Path#value() value} - Free-form Swagger JSON.

The most typical scenario is to simply use the value field to define path parameter names:

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 ) {...}

This is functionally equivalent to the following code:

@RestMethod(name=GET, path="/myurl/{foo}/{bar}/{baz}/*") public void doGet(RestRequest req) { RequestPath p = req.getPathMatch(); String foo = p.getString("foo"); int bar = p.get("bar", int.class); UUID baz = p.get("baz", UUID.class); String remainder = p.getRemainder(); }

Note that the path variable name "/*" can be used to represent the remainder of the path match.

The special name "*" (or blank) can be used to represent all values. When used, the data type must be a Map or bean.

Examples:

// Multiple values passed as a map. @RestMethod(name=GET, path="/{a}/{b}/{c}/*") public void doGet(@Path("*") Map<String,Object> map) {...}

// Same, but name "*" is inferred. @RestMethod(name=GET, path="/{a}/{b}/{c}/*") public void doGet(@Path Map<String,Object> map) {...}

// Multiple values passed as a bean. @RestMethod(name=GET, path="/{a}/{b}/{c}/*") public void doGet(@Path MyBean bean) {...}

The registered {@link oajr.RestContext#REST_partParser REST_partParser} is used to convert strings to POJOs and controls what POJO types are supported.
By default, this is the {@link oaj.oapi.OpenApiParser} which supports the standard Swagger-based rules for parsing.

For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. "1,2,3|4,5,6|7,8,9") can be converted to a 2-dimensional array of Longs:

@RestMethod(method="POST", path="/testPath/{pathParam}") public void testPath( @Path( name="pathParam", collectionFormat="pipes", items=@SubItems( collectionFormat="csv", type="integer", format="int64", minimum="0", maximum="100" minLength=1, maxLength=10 ), minLength=1, maxLength=10 ) Long[][] pathParameter ) {...}

Input will be converted based on the types and formats defined in the schema definition.
Input validations such as minLength/maxLength that don't match the input will result in automatic 400 Bad Request responses.

For more information about valid parameter types, see {@doc juneau-marshall.OpenApiDetails.Parsers OpenAPI Parsers}

The @Path annotation is also used for supplying swagger information about the HTTP part.
This information is used to populate the auto-generated Swagger documentation and UI.

Examples:

// Normal @Path( name="name", description="Pet name", required=true, example="Doggie" )

// Free-form // Note the extra field @Path( name="name", api={ "description: 'Pet name',", "required: true,", "example: 'Doggie'," "x-extra: 'extra field'" } )

{@doc DefaultRestSvlVariables} (e.g. "$L{my.localized.variable}") are supported on annotation fields.

Example:

@Path( description="$L{PetNameDescription}" )

See Also:

• {@link oajr.RequestPath}
• {@doc juneau-rest-server.OpenApiSchemaPartParsing}