Annotations

The org.apache.juneau.http package contains annotations for defining both server and client side APIs.

The server-side APIs also use it for producing auto-generated Swagger documentation through the REST API itself.

Contact Content FormData HasFormData HasQuery Header License Part Path PathRemainder Query Request Response StatusCode Tag Url

These annotations are used in a variety of places in the server and client side REST interfaces, especially for remote proxies. They are provided by the juneau-rest-common module, so they are available to both server and client code without depending on either.

All of them have runtime retention.

HTTP part annotations

These bind a method parameter (or bean property or type) to one part of an HTTP request. All of the following are @Inherited. @Header, @Query, @FormData, @Path and @PathRemainder may be applied to parameters, methods, types and fields; the others are as noted.

Annotation	Purpose	Notable attributes
@Content	The request body. Targets: parameter, method, type.	def, description, summary, schema
@Header	A request header.	name, value (alias for name), def, description, summary, schema
@Query	A query parameter.	name, value, def, description, summary, schema
@FormData	A form-data entry.	name, value, def, description, summary, schema
@Path	A path variable.	name, value, def, description, summary, schema
@PathRemainder	The remainder of the path after the pattern match.	def, description, schema
@HasQuery	Whether the request has the named query parameter. Parameter only.	name, value, description
@HasFormData	Whether the request has the named form-data parameter. Parameter only.	name, value, description

Request and response bean annotations

Annotation	Purpose	Notable attributes
@Request	Marks an interface or parameter as a request bean exposing several HTTP parts through getters. Targets: parameter, type, method.	description
@Response	Marks a type, method or parameter as a response bean.	description, summary, examples, headers, schema
@StatusCode	Denotes an HTTP response status code.	value (int array), description

Client-only (remote proxy) annotations

Annotation	Purpose	Notable attributes
@Part	A multipart/form-data part on a remote-proxy method parameter. Parameter only.	name, value, fileName, contentType
@Url	A remote-proxy parameter supplying the entire request URL. Parameter only.

Swagger metadata annotations

These are not applied to parameters. They are used as nested values of @Swagger (contact, license and tags), which is supplied through @Rest(swagger=...), to populate the generated Swagger document.

Annotation	Purpose	Attributes
@Contact	Contact information for the API.	name, url, email, description
@License	License information for the API.	name, url, description
@Tag	Metadata for a single Swagger tag.	name, description, externalDocs

Where they are described

• Server usage: HTTP Part Annotations, Request Beans, Response Beans and Java Method Parameters.
• Client usage with remote proxies: REST Proxies and its @Content, @FormData, @Query, @Header, @Path, @Request and @Response pages.
• Swagger generation: Swagger.
• The server-side @Rest/@RestOp annotations themselves: @Rest and @RestOp.