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

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