Question

我正在使用Java的Swagger Core 2.0.2生成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的{{1}}数组，但没有。说明也丢失了。

我尝试了模式设置的多种组合，但无济于事。我非常感谢您对我做错事的任何帮助。

先谢谢了。

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

但是，它不能完全解决我的问题，因为我仍然不知道如何在description中设置otherDTO的{{1}}。但这使我更近了一步。

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

1 个答案: