Swagger ignores Schema properties for referenced schemas

Question

I am using Swagger Core 2.0.2 for Java to generate an OpenAPI documentation. Among others, I have the following class 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 is described as follows:

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

My problem is that neither the description nor the required field above the otherDTO field has any effect.

The resulting openapi.json looks like this:

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

I was expecting the SomeDTO schema to have a required array containing OtherDTO, which it does not. The description is also lost.

I have tried numerous combinations of Schema settings, to no avail. I would highly appreciate any help to understand what I am doing wrong.

Thanks in advance.

Answer 1

I have found a solution to part of my problem.

The problem is caused by the fact that when using a $ref element, sibling elements are ignored. So elements (description, name etc.) related to the referenced element need to be specified as a @Schema in the referenced object itself (OtherDTO in the example above). Specifying these elements in the parent object (e.g. SomeDTO) will leave them ignored.

However, the schema elements in the referenced element do not seem to propagate up to the parent object. So, to make otherDTO a required field in SomeDTO, I need to add requiredProperties = { "OtherDTO" }) to SomeDTO's schema.

Here is the updated code:

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

However, it does not solve my problem completely, as I still can't figure out how to set the description of otherDTO in SomeDTO. But it gets me a step closer.