jax-rs - 如何使用 JAX-RS 为 OpenAPI 定义声明响应数组类型？

Question

我正在使用 JAX-RS、Microprofile 和 Payara 5 构建 REST 服务。我的方法返回类型为 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实现中存在错误，因为我检查了此页面上的示例guide-microprofile-openapi

相同的实现有 2 代不同的 openapi(Payara 和 OpenLiberty)

帕亚拉:

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

开放自由:

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