Swagger忽略引用模式的Schema属性

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

我的问题是， otherDTO字段上方的description和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数组，但它没有。 描述也丢失了。

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

提前致谢。

Answer 1

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

问题是由于使用$ref元素时忽略了兄弟元素。 因此，与引用元素相关的元素（ description ， name等）需要在引用的对象本身中指定为@Schema （上OtherDTO中的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 。 但它让我更近了一步。