@Target(value={METHOD,TYPE}) @Retention(value=RUNTIME) @Inherited @Repeatable(value=APIResponses.class) public @interface APIResponse
When this annotation is applied to a JAX-RS 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 JAX-RS 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 or toResponse
method, it allows
developers to describe the API response that will be added to a generated OpenAPI operation based on a JAX-RS method
that declares an Exception
of the type handled by the ExceptionMapper
.
@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(); } }
Modifier and Type | Optional Element and Description |
---|---|
Content[] |
content
An array containing descriptions of potential response payloads for different media types.
|
java.lang.String |
description
A short description of the response.
|
Extension[] |
extensions
List of extensions to be added to the
APIResponse 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.
|
java.lang.String |
name
The unique name to identify this response.
|
java.lang.String |
ref
Reference value to a Response object.
|
java.lang.String |
responseCode
The HTTP response code, or 'default', for the supplied response.
|
public abstract java.lang.String description
public abstract java.lang.String responseCode
public abstract Header[] headers
RFC7230 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
public abstract Link[] links
public abstract Content[] content
public abstract java.lang.String name
Components
. The name will be used as the key to add this
response to the 'responses' map for reuse.public abstract java.lang.String ref
This property provides a reference to an object defined elsewhere. This property and all other properties are mutually exclusive. If other properties are defined in addition to the ref property then the result is undefined.
public abstract Extension[] extensions
APIResponse
model corresponding to the containing annotation.