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

Question

我使用 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也不是required上述场otherDTO场有任何影响。

结果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架构有一个required包含的数组OtherDTO，但它没有。描述也丢失了。

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

提前致谢。

Answer 1

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

该问题是由于使用$ref元素时，兄弟元素被忽略而引起的。因此，与被引用元素相关的元素（description等）需要在被引用对象本身中name指定为 a （在上面的示例中）。在父对象中指定这些元素（例如）将使它们被忽略。@SchemaOtherDTOSomeDTO

但是，引用元素中的架构元素似乎不会传播到父对象。因此，要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;
}

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