org.eclipse.microprofile.openapi.annotations.responses

Annotation Type APIResponseSchema

@Target(value=METHOD)
 @Retention(value=RUNTIME)
 @Inherited
public @interface APIResponseSchema

The APIResponseSchema annotation corresponds to an individual schema in the OpenAPI Response model object which describes a single response from an API Operation. This annotation provides a short-hand way to specify a simple response that would otherwise be specified using @APIResponse and that typically could not be determined by scanning the resource method alone.

The following annotation usages are equivalent to the OpenAPI annotation scanner runtime.

 @APIResponse(content = { @Content(schema = @Schema(implementation = MyResponseObject.class)) })

 @APIResponseSchema(MyResponseObject.class)
 

When this annotation is applied to a method the response is added to the responses defined in the corresponding OpenAPI operation with a default response code and description that correspond to the method's HTTP method annotation and return type. Any media types that apply to the resource method from either a method-level or class-level @Produces annotation will result in those media types applying to the OpenAPI response model.

If not specified, default responseCode and responseDescription values shall be determined according to the responseCode and responseDescription documentation.

 @GET
 @Path("{id}")
 @APIResponseSchema(value = MyResponseObject.class, responseDescription = "Success", responseCode = "200")
 public Response getById(@PathParam("{id}") long id) {
     MyResponseObject entity = service.load(id);
     return Response.status(200).entity(entity).build();
 }
 

Since:

2.0

See Also:

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

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
Class<?>	value Provides a Java class as implementation for this schema.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String	responseCode The HTTP response code, or 'default', for the supplied response.
String	responseDescription A short description of the response.

Element Detail

value

public abstract Class<?> value

Provides a Java class as implementation for this schema. The class will undergo introspection to determine any applicable Schema attributes to be applied to the OpenAPI response model.

Returns:

a class that implements this schema

responseDescription

public abstract String responseDescription

A short description of the response. It is a REQUIRED property in the OpenAPI document.

If no value is specified, the default value will set to the description given by the HTTP/1.1 documentation for the responseCode in use.

Returns:

description of the response.

Default:

""

responseCode

public abstract String responseCode

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

If no value is specified, a default shall be determined using REST conventions as follows:

• If the method's return type is void and the HTTP method is @POST, the code will be 201.
• Otherwise, if the method's return type is void the method does not list a JAX-RS AsyncResponse parameter, the code will be 204.
• Otherwise, the code will be 200.

Returns:

HTTP response code for this response instance or default

Default:

""