如何使用JAX-RS声明OpenAPI定义的响应数组类型

Question

我正在使用JAX-RS，MicroProfile和Payara 5构建REST服务5。我的方法返回类型Response的对象。响应本身包含MyClass的列表。实现看起来像这样：

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();
}

生成的OpenAPI定义看起来像这样：

/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: {}

您可以看到，响应类型中缺少myClass.class的定义。如何将该类型添加到定义中？@ApiResponse注释是正确的方法吗？

Answer 1

我今天用最新的Payara 5.191对此进行了测试，但它也对我不起作用。当前的Payara实施中似乎有一个错误，因为我检查了此页面上的示例指南Microprofile-openapi

相同的实现具有2个不同的Openapi世代（Payara和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