Swagger-core: Swagger ignores @Schema(required = true) on non-primitive types when generating the openapi.yaml

Created on 29 Jul 2019 · 3Comments · Source: swagger-api/swagger-core

I have a reproducible issue where Swagger will ignore @Schema(required = true) annotations on Object fields when generating the openapi.yaml specification.

To reproduce this, follow the general steps:
1) Clone the swagger-samples repo at 2.0 (https://github.com/swagger-api/swagger-samples/tree/2.0)
2) Change the root pom.xml to use Swagger 2.0.8 (non-snapshot)
3) Navigate to the java-jersey2-minimal
4) Under the Pet object, modify the code to look like the following:

  @XmlElement(name = "id")
  @Schema(required = true)
  public long getId() {
    return id;
  }

  public void setId(long id) {
    this.id = id;
  }

  @XmlElement(name = "category")
  @Schema(required = true)
  public Category getCategory() {
    return category;
  }

(Here, we add @Schema(required = true) required tags to both the "id" and "category" fields)

5) Build the sample as described (https://github.com/swagger-api/swagger-samples/tree/2.0/java/java-jersey2-minimal) and generate the yaml

After following these steps, we see that the generated yaml contains the following:

...
Pet:
      required:
      - id
      type: object
      properties:
        id:
          type: integer
          format: int64
        category:
          $ref: '#/components/schemas/Category'
...

This is unexpected. I would expect that adding @Schema(required = true) to the id and category fields would add both id and category to the "required" section of the Pet yaml. Yet, we only see id added. I've tested this in other scenarios, and it seems it only adds the field as "required" if it's some OpenApi primitive (i.e., it does not have a $ref).

If you manually add category to the "required" section, it will properly show that category is required in the Swagger UI. But without manually adding it, category will not have the same red asterisk that the other required fields have.

Because of this issue, it's harder to specify what objects in a complex type must be filled out in API requests and which may be omitted. This is especially helpful when using Immutables, as some fields in Immutables will use a default if nothing is specified, while for other fields immutables will throw an exception if it's missing.

Source