org.eclipse.microprofile.openapi.annotations.responses

## Annotation Type APIResponse

    @Target(value={METHOD,TYPE})
     @Retention(value=RUNTIME)
     @Inherited
     @Repeatable(value=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 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();
         }
     }

See Also:
  "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#responseObject"

### Optional Element Summary

Optional Elements
`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 Detail

#### description

    public abstract 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

    public abstract 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

    public abstract 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

    public abstract 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

    public abstract Content[] content

An array containing descriptions of potential response payloads for different media types.

Returns:
  content of this response instance

Default:
  {}

#### name

    public abstract 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

    public abstract String ref

Reference value to a Response object.

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.

Returns:
  reference to a response

Default:
  ""

#### extensions

    public abstract 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:
  {}