Swagger 忽略引用架构的架构属性答案

【问题标题】：Swagger ignores Schema properties for referenced schemasSwagger 忽略引用架构的架构属性
【发布时间】：2018-08-03 11:43:14
【问题描述】：

我正在使用 Swagger Core 2.0.2 for Java 来生成 OpenAPI 文档。其中，我有以下课程SomeDTO：

@Schema(name = "SomeDTO", description = "some description")
public class SomeDTO {
  @Schema(description = "description of name")
  private String name;
  @Schema(required = true, description = "description of OtherDTO")
  private OtherDTO otherDTO;
}

OtherDTO描述如下：

public class OtherDTO {
  @Schema(required = true)
  private String someField;
  private String someOtherField;
}

我的问题是description 和otherDTO 字段上方的required 字段都没有任何效果。

生成的openapi.json 如下所示：

    "components": {
      "schemas": {
        "SomeDTO" : {
          "type": "object",
          "properties": {
            "name": {
              "type" : "string"
            }
            "otherDTO" : {
              "$ref": "#/components/schemas/OtherDTO"
            }
          },
          "description": "some description"
        },
        "OtherDTO": {
          "required": ["someField"],
          "type": "object",
          "properties": {
            "somefield": {
              "type": "string"
            },
            "someOtherField": {
              "type": "string"
            }
          }
        }
      }
    }

我期待SomeDTO 架构有一个包含OtherDTO 的required 数组，但它没有。描述也丢失了。

我尝试了多种架构设置组合，但均无济于事。我将非常感谢任何帮助以了解我做错了什么。

提前致谢。

【问题讨论】：

标签： java swagger swagger-2.0 openapi

【解决方案1】：

我找到了部分问题的解决方案。

问题是由于在使用$ref元素时，sibling elements are ignored.所以与被引用元素相关的元素（description、name等）需要在中指定为@Schema引用的对象本身（上例中的OtherDTO）。在父对象中指定这些元素（例如SomeDTO）将使它们被忽略。

但是，被引用元素中的架构元素似乎不会传播到父对象。因此，要使otherDTO 成为SomeDTO 中的必填字段，我需要将requiredProperties = { "OtherDTO" }) 添加到SomeDTO 的架构中。

这是更新后的代码：

SomeDTO

@Schema(name = "SomeDTO", description = "some description",
requiredProperties = { "OtherDTO" })
public class SomeDTO {
  @Schema(description = "description of name")
  private String name;
  private OtherDTO otherDTO;
}

OtherDTO

@Schema(name = "OtherDTO", description = "Description of OtherDTO")
public class OtherDTO {
  @Schema(required = true)
  private String someField;
  private String someOtherField;
}

但是，它并没有完全解决我的问题，因为我仍然不知道如何在SomeDTO 中设置otherDTO 的description。但它让我更近了一步。

【讨论】：