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

# Annotation Type APIResponseSchema

@Target(METHOD) @Retention(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
Description
`Class<?>`
`value`
Provides a Java class as implementation for this schema.

## Optional Element Summary

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

## Element Details

### value

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

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

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:
  ""