如何使用Swagger Core（springdoc-openapi）生成OpenAPI任意类型？

Question

public class TypeWithObject {
    private Object value;

    public Object getValue() { return value; }
    public void setValue(Object value) { this.value = value; }
}

OpenAPI3.0规范规定，没有任何类型的模式将匹配任何数据类型。

没有类型的模式匹配任何数据类型--数字、字符串、对象等等。

因此，对此进行建模的正确方法是下面的Swagger定义，其中value没有type属性：

{
  "openapi": "3.0.1",
  "info": {
    "title": "OpenAPI definition",
    "version": "v0"
  },
  "components": {
    "schemas": {
      "TypeWithObject": {
        "type": "object",
        "properties": {
          "value": {}
        }
      }
    }
  }
}

但是，每个开放问题Swagger-core#3834，JavaObject值都映射到OpenAPIObject类型，而不是任意类型。如上所述，这意味着这样的API返回或接受不是OpenAPI对象的类型是不正确的，例如字符串、数字、布尔等。

我做了各种尝试，试图让应用程序将此类型生成为OpenAPI任意类型，但都无济于事。在使用自定义ModelConverter使用带有空类型的Swagger模式时，我发现了一件事，Swagger核心最终将类型转换为对象作为其内部处理的一部分。这目前被记录为Swagger Core的开放特性请求，如Swagger-Core#4014。

说完这一切：如何让我生成的类型使用OpenAPI任意类型？

Answer 1

一种方法是在单独的文件中手动定义任意类型模式，并使用OpenAPI$ref关键字（使用@schema(ref=“...”）)引用该类型。

api-docs-anyvalue.yml:

components:
  schemas:
    AnyValue: {}

java prettyprint-override">import io.swagger.v3.oas.annotations.media.Schema;

public class TypeWithObject {
    @Schema(ref = "api-docs-anyvalue.yml#/components/schemas/AnyValue")
    private Object value;

    public Object getValue() { return value; }
    public void setValue(Object value) { this.value = value; }
}

结果：

{
  "openapi": "3.0.1",
  "info": {
    "title": "OpenAPI definition",
    "version": "v0"
  },
  "components": {
    "schemas": {
      "TypeWithObject": {
        "type": "object",
        "properties": {
          "value": {
            "$ref": "api-docs-anyvalue.yml#/components/schemas/AnyValue"
          }
        }
      }
    }
  }
}