How can I declare the response array type for OpenAPI definition with JAX-RS?

Question

I'm building a REST service with JAX-RS, Microprofile and Payara 5. My method returns an object of type Response. The response itself contains a List of MyClass. The implementation looks like this:

import org.eclipse.microprofile.openapi.annotations.enums.SchemaType;
import org.eclipse.microprofile.openapi.annotations.media.Content;
import org.eclipse.microprofile.openapi.annotations.media.Schema;
import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;

@GET
@Path("/{a}/{b}/{c}")
@APIResponse(content = @Content(schema = @Schema(type = SchemaType.ARRAY, implementation = MyClass.class)))
public Response getMyClass(@PathParam("a") String a,
                           @PathParam("b") String b,
                           @PathParam("c") String c) {
    return Response
            .ok()
            .entity(new ArrayList<>())
            .build();
}

The generated OpenAPI definition looks like this:

/api/translations/{a}/{b}/{c}:
  get:
    operationId: getMyClass
    parameters:
    - name: a
      in: path
      required: true
      style: simple
      schema:
        type: string
    - [...]
    responses:
      default:
        description: Default Response.
        content:
          '*/*':
            schema:
              type: array
              items: {}

As you can see, the definition of MyClass.class is missing in the response type. How can I add that type to the definition? Is the @ApiResponse annotation the correct way to achieve this?

Answer 1

I tested this today with the newest payara 5.191 and it did not worked for me too. It seems that there is a bug in the current payara implementation, because I checked the example on this page guide-microprofile-openapi

The same implementation has 2 different openapi generations (Payara and OpenLiberty)

Payara:

openapi: 3.0.0
info:
  title: Deployed Resources
  version: 1.0.0
servers:
- url: https://10.0.0.72:8080/ipma
  description: Default Server.
paths:
  /resources/server:
    get:
      summary: List servers.
      description: 'Returns all servers '
      operationId: getServers
      responses:
        default:
          description: Special description
          content:
            application/json:
              schema:
                type: array
  /resources/server/{id}:
    get:
      summary: get server by id.
      description: 'return one server with the specified id'
      operationId: getServerById
      parameters:
      - name: id
        in: query
        style: simple
        schema:
          type: number
      responses:
        default:
          description: Special description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Server'
components:
  schemas:
    Server:
      properties:
        name:
          type: string
          example: test
        id:
          type: number
          example: "0"
      description: foo

OpenLiberty:

openapi: 3.0.0
info:
  title: Deployed APIs
  version: 1.0.0
servers:
- url: http://localhost:9080
paths:
  /resources/server/{id}:
    get:
      summary: get server by id.
      description: 'return one server with the specified id'
      operationId: getServerById
      parameters:
      - name: id
        in: query
        schema:
          type: integer
          format: int64
      responses:
        default:
          description: Special description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Server'
  /resources/server:
    get:
      summary: List servers.
      description: 'Returns all servers '
      operationId: getServers
      responses:
        default:
          description: Special description
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Server'
components:
  schemas:
    Server:
      required:
      - id
      - name
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 0
        name:
          type: string
          example: test
      description: foo