@Schema(allowableValues) on an enum should replace the list instead of adding to it

[mjustin]

Describe the bug

Using @Schema(allowableValues = {...}] to declare the list of values for an enum adds to the generated list, rather than replacing it. This surprised me; as I would have expected the presence of this annotation to define the list, rather than add to it.

I discovered this when attempting to work around #1101. Here's a relevant Stack Overflow post.

To Reproduce

build.gradle

plugins {
    id 'org.springframework.boot' version '2.5.3'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    id 'java'
}

sourceCompatibility = '11'

repositories {
    mavenCentral()
}

dependencies {
    implementation 'io.swagger.core.v3:swagger-annotations:2.1.10'
    implementation 'org.springdoc:springdoc-openapi-ui:1.5.10'
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

package com.example.springdoc;

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/playingCard")
public class PlayingCardController {
    @PostMapping
    public PlayingCard echo(@RequestBody PlayingCard card) {
        return card;
    }
}

package com.example.springdoc;

import io.swagger.v3.oas.annotations.media.Schema;

public class PlayingCard {
    private Suit suit;
    private Integer value;

    public Suit getSuit() { return suit; }
    public void setSuit(Suit suit) { this.suit = suit; }
    public Integer getValue() { return value; }
    public void setValue(Integer value) { this.value = value; }

    @Schema(allowableValues = {"Hearts", "Diamonds", "Clubs", "Spades"})
    public enum Suit {
        HEARTS, DIAMONDS, CLUBS, SPADES;
    }
}

Output of http://localhost:8080/v3/api-docs:

{
  "openapi": "3.0.1",
  "info": {
    "title": "OpenAPI definition",
    "version": "v0"
  },
  "servers": [
    {
      "url": "http://localhost:8080",
      "description": "Generated server url"
    }
  ],
  "paths": {
    "/playingCard": {
      "post": {
        "tags": [
          "playing-card-controller"
        ],
        "operationId": "echo",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlayingCard"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/PlayingCard"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PlayingCard": {
        "type": "object",
        "properties": {
          "suit": {
            "type": "string",
            "enum": [
              "HEARTS",
              "DIAMONDS",
              "CLUBS",
              "SPADES",
              "Hearts",
              "Diamonds",
              "Clubs",
              "Spades"
            ]
          },
          "value": {
            "type": "integer",
            "format": "int32"
          }
        }
      }
    }
  }
}

Expected behavior

Rather than using both the full list of enum values as well as those listed in @Schema(allowableValues=[...]), I expect it to return just those values listed in @Schema(allowableValues=[...]).

For the above example, I would expect "enum":["Hearts","Diamonds","Clubs","Spades"] to be returned. Instead, "enum": ["HEARTS","DIAMONDS","CLUBS","SPADES","Hearts","Diamonds","Clubs","Spades"] is returned.

Additional context

This was an attempted workaround for the fact that the @JsonValue enum is not used (as requested by #1101). Fixing that issue would remove my personal need for this fix, though if my intuition is right that this is not the desired behavior, it likely makes sense to fix this regardless.

[bnasslahsen]

@mjustin,

Not related directly to springdoc-openapi. But depends on swagger-core implementation swagger-api/swagger-core#3566

Here is the workaround, as described here swagger-api/swagger-core#2949:

@Schema(type = "String", allowableValues = {"Hearts", "Diamonds", "Clubs", "Spades"})

[mjustin]

Thank you; didn't realize this was caused by a different library (or that there was a posted workaround).