使用Quarkus同步OpenAPI和JSON-B配置

Question

我正试图按照官方指南，使用RESTEasy和JSON-B启动并运行REST服务。我还添加了对OpenAPI的支持，以便按照该指南测试服务。

这两个部分都独立工作，服务会正确返回硬编码的演示数据。Swagger UI显示可用的路由并允许调用它们。

然而，它并不像我喜欢的那样平滑。。。

玩玩，我创建了一个路由，返回一个包含Instant的对象。打电话时，我用一个ISO 8601格式的属性字符串表示，正如我所料。

但是，属性的关联架构为

Instant:
  type: object
  properties:
    nanos:
      format: int32
      type: integer
    seconds:
      format: int64
      type: integer
    epochSecond:
      format: int64
      type: integer
    nano:
      format: int32
      type: integer

这与实际返回的内容不一致。我有点明白它的来历。显然，quarkus smallrye openapi在检查quarkus resteasy jsonb使用的即时时使用了不同的设置。

对于后者，我已经弄清楚了可以使用自定义JsonbAdapter来操作格式。例如：

public class JsonbInstantTypeAdapter implements JsonbAdapter<Instant, OffsetDateTime> {
    @Override
    public OffsetDateTime adaptToJson(Instant obj) {
        return OffsetDateTime.ofInstant(obj, ZoneId.systemDefault());
    }

    @Override
    public Instant adaptFromJson(OffsetDateTime obj) {
        return obj.toInstant();
    }
}

public class TestTimestamps {
    @JsonbTypeAdapter(JsonbInstantTypeAdapter.class)
    public Instant getDueTime() {
        return Instant.now();
    }
}

这导致在转换为系统时区后，即时被序列化，调试时更容易读取。

我只能部分了解如何调整模式。注释方法如下：

public class TestTimestamps {
    @Schema(type = SchemaType.STRING, format = "date-time")
    public Instant getDueTime() {
        return Instant.now();
    }
}

结果生成了一个适当的示例值，但生成的模式仍然知道这是一个瞬间，因此生成为

dueTime:
    allOf:
        - $ref: '#/components/schemas/Instant'
        - format: date-time
          type: string

理想情况下，无论如何，我都不想单独注释每个方法。

有没有一种方法可以在项目范围内配置为为给定类型使用某个适配器？有没有一种方法可以确保生成的OpenAPI模式实际上代表的是适应的类型而不是原始类型？

Answer 1

在修复此问题之前，一个短期的即时解决方案应该是使用模式注释的实现属性。smallrye open api中的注释扫描器在给出实现时将忽略bean方法/字段的类型（这将消除示例输出中的$ref）。这种方法也适用于任何其他未在OpenAPI中使用其“自然”类型正确表示的Java类型。

public class TestTimestamps {
    @Schema(implementation = String.class, format = "date-time")
    public Instant getDueTime() {
        return Instant.now();
    }
}

Answer 2

MicroProfile规范允许您覆盖特定类的模式

将此添加到Quarkus应用程序中。属性将覆盖日期架构

mp.openapi.schema.java.util.Date = { \
  "name": "EpochMillis" \
  "type": "number", \
  "format": "int64", \
  "description": "Milliseconds since January 1, 1970, 00:00:00 GMT" \
}

这可以解决您的即时问题。看见https://github.com/eclipse/microprofile-open-api/blob/master/spec/src/main/asciidoc/microprofile-openapi-spec.adoc#core-配置