Top Description Methods
org.eclipse.microprofile.openapi.annotations.responses

public @Interface APIResponse

extends Annotation
Annotations
@Target:METHOD, TYPE
@Retention:RUNTIME
@Inherited
@Repeatable:APIResponses
Imports
java.lang.annotation.ElementType, .Inherited, .Repeatable, .Retention, .RetentionPolicy, .Target, org.eclipse.microprofile.openapi.annotations.extensions.Extension, org.eclipse.microprofile.openapi.annotations.headers.Header, org.eclipse.microprofile.openapi.annotations.links.Link, org.eclipse.microprofile.openapi.annotations.media.Content
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

Method Summary

Modifier and TypeMethod and Description
public Content[]

Returns:

content of this response instance
content()

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

public String

Returns:

description of the response.
description()

A short description of the response.

public Extension[]

Returns:

array of extensions
extensions()

List of extensions to be added to the APIResponse model corresponding to the containing annotation.

public Header[]

Returns:

array of headers for this response instance
headers()

An array of response headers.

public String

Returns:

this response's name
name()

The unique name to identify this response.

public String

Returns:

reference to a response
ref()

Reference value to a Response object.

public String

Returns:

HTTP response code for this response instance or default
responseCode()

The HTTP response code, or 'default', for the supplied response.

Inherited from java.lang.annotation.Annotation:
annotationTypeequalshashCodetoString

Method Detail

contentback to summary
public Content[] content()

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

Returns:Content[]

content of this response instance

descriptionback to summary
public String description()

A short description of the response. It is a REQUIRED property unless this is only a reference to a response instance.

Returns:String

description of the response.

extensionsback to summary
public Extension[] extensions()

List of extensions to be added to the APIResponse model corresponding to the containing annotation.

Returns:Extension[]

array of extensions

Since
3.1
headersback to summary
public 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:Header[]

array of headers for this response instance

linksback to summary
public Link[] links()

An array of operation links that can be followed from the response.

Returns:Link[]

array of operation links for this response instance

nameback to summary
public String name()

The unique name to identify this response. Only REQUIRED when the response is defined within org.eclipse.microprofile.openapi.annotations.Components. The name will be used as the key to add this response to the 'responses' map for reuse.

Returns:String

this response's name

refback to summary
public 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:String

reference to a response

responseCodeback to summary
public String responseCode()

The HTTP response code, or 'default', for the supplied response. May only have 1 default entry.

Returns:String

HTTP response code for this response instance or default