Annotation Type APIResponse
-
@Target({METHOD,TYPE}) @Retention(RUNTIME) @Inherited @Repeatable(APIResponses.class) public @interface APIResponse
The APIResponse annotation corresponds to the OpenAPI Response model object which describes a single response from an API Operation, including design-time, static links to operations based on the response.When this annotation is applied to a Jakarta REST method the response is added to the responses defined in the corresponding OpenAPI operation. If the operation already has a response with the specified responseCode the annotation on the method is ignored.
@APIResponse(responseCode = "200", description = "Calculate load size", content = { @Content(mediaType = "application/json", Schema = @Schema(type = "integer"))}) @GET public getLuggageWeight(Flight id) { return getBagWeight(id) + getCargoWeight(id); }
When this annotation is applied to a Jakarta REST resource class, the response is added to the responses defined in all OpenAPI operations which correspond to a method on that class. If an operation already has a response with the specified responseCode the response is not added to that operation.
When this annotation is applied to an
ExceptionMapper
class ortoResponse
method, it allows developers to describe the API response that will be added to a generated OpenAPI operation based on a Jakarta REST method that declares anException
of the type handled by theExceptionMapper
.@Provider public class NotFoundExceptionMapper implements ExceptionMapper<NotFoundException> { @Override @APIResponse(responseCode = "404", description = "Not Found") public Response toResponse(NotFoundException t) { return Response.status(404) .type(MediaType.TEXT_PLAIN) .entity("Not found") .build(); } }
- See Also:
- OpenAPI Specification Response Object
-
-
Optional Element Summary
Optional Elements Modifier and Type Optional Element Description Content[]
content
An array containing descriptions of potential response payloads for different media types.String
description
A short description of the response.Extension[]
extensions
List of extensions to be added to theAPIResponse
model corresponding to the containing annotation.Header[]
headers
An array of response headers.Link[]
links
An array of operation links that can be followed from the response.String
name
The unique name to identify this response.String
ref
Reference value to a Response object.String
responseCode
The HTTP response code, or 'default', for the supplied response.
-
-
-
Element Detail
-
description
String description
A short description of the response. It is a REQUIRED property unless this is only a reference to a response instance.- Returns:
- description of the response.
- Default:
- ""
-
-
-
responseCode
String responseCode
The HTTP response code, or 'default', for the supplied response. May only have 1 default entry.- Returns:
- HTTP response code for this response instance or default
- Default:
- "default"
-
-
-
headers
Header[] headers
An array of response headers. Allows additional information to be included with response.RFC7230 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
- Returns:
- array of headers for this response instance
- Default:
- {}
-
-
-
links
Link[] links
An array of operation links that can be followed from the response.- Returns:
- array of operation links for this response instance
- Default:
- {}
-
-
-
content
Content[] content
An array containing descriptions of potential response payloads for different media types.- Returns:
- content of this response instance
- Default:
- {}
-
-
-
name
String name
The unique name to identify this response. Only REQUIRED when the response is defined withinComponents
. The name will be used as the key to add this response to the 'responses' map for reuse.- Returns:
- this response's name
- Default:
- ""
-
-
-
ref
String ref
Reference value to a Response object.This property provides a reference to an object defined elsewhere. This property may be used with
description()
but is mutually exclusive with all other properties. If properties other thandescription
are defined in addition to theref
property then the result is undefined.- Returns:
- reference to a response
- Default:
- ""
-
-
-
extensions
Extension[] extensions
List of extensions to be added to theAPIResponse
model corresponding to the containing annotation.- Returns:
- array of extensions
- Since:
- 3.1
- Default:
- {}
-
-