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
      java.lang.Class<?> value
      Provides a Java class as implementation for this schema.

    • Optional Element Summary

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

    • Element Detail

      • value

        java.lang.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

        java.lang.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

        java.lang.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:
        ""