java - 如何使用 Swagger Core (springdoc-openapi) 生成 OpenAPI 任意类型？

Question

我正在开发一个使用 springdoc-openapi 的应用程序为其 Spring Controller 生成 OpenAPI v3 端点的库。该库使用 Swagger Core用于 Java 对象到 OpenAPI 模式的实际映射。

Controller 使用一个请求/响应类型，其中包含一个 Object 类型的属性。

public class TypeWithObject {
    private Object value;

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

因此，此类型可以是 data types 中的任何一个由 OpenAPI 定义:string、number、integer、boolean、array 或对象。请注意，object 是与其他类型不同的类型；例如字符串或 boolean 不是对象。

OpenAPI 3.0 Specification指定没有任何类型的架构将匹配任何数据类型。

A schema without a type matches any data type – numbers, strings, objects, and so on.

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

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

但是，每个未决问题 swagger-core#3834 ，Java Object 值映射到 OpenAPI object 类型，而不是任意类型。如上所述，这意味着此类 API 返回或接受非 OpenAPI 对象 的类型是不正确的，例如 string、数字、 boolean 值等

我做了各种尝试让应用程序生成此类型作为 OpenAPI 任意类型，但没有成功。我在使用自定义 ModelConverter 时发现的一件事使用 Swagger Schema使用 null type 的原因是 Swagger Core 最终将类型转换为 object 作为其内部处理的一部分。目前，这被记录为 Swagger Core 的开放功能请求:swagger-core#4014 .

综上所述:如何让生成的类型使用 OpenAPI 任意类型？

Answer 1

一种方法是在单独的文件中手动定义任意类型架构，并使用 OpenAPI $ref 关键字(使用 @Schema(ref="...") 应用)来引用此类型。

api-docs-anyvalue.yml:

components:
  schemas:
    AnyValue: {}

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"
          }
        }
      }
    }
  }
}