Module org.eclipse.microprofile.openapi
Package org.eclipse.microprofile.openapi.annotations.responses

# 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 or `toResponse` 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 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();
         }
     }

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 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.
`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 Details

### 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 within `Components`. 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 than `description` are defined in addition to the `ref` property then the result is undefined.

Returns:
  reference to a response

Default:
  ""

### extensions

Extension[] extensions
List of extensions to be added to the `APIResponse` model corresponding to the containing annotation.

Returns:
  array of extensions
Since:
  3.1

Default:
  {}