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 。 但它讓我更近了一步。