feat: change Schema.required from List to Set (#5027)

  - Change internal storage from List<String> to Set<String> using TreeSet
  - Keep public API compatible (getRequired() returns a defensive copy as List<String>)
  - Make addRequiredItem() consistent with setRequired(): ignore items not present in properties
  - Add JavaDoc to getRequired() explaining the defensive copy behavior
  - Add unit tests for duplicate handling, sorting, and consisteny

Author: yht0827

modules/swagger-models/src/main/java/io/swagger/v3/oas/models/media/Schema.java

@@ -10,13 +10,13 @@
 
 import java.math.BigDecimal;
 import java.util.ArrayList;
-import java.util.Collections;
 import java.util.LinkedHashMap;
 import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
 import java.util.Set;
+import java.util.TreeSet;
 
 /**
  * Schema
@@ -91,7 +91,7 @@ public String toString() {
     private Boolean uniqueItems = null;
     private Integer maxProperties = null;
     private Integer minProperties = null;
-    private List<String> required = null;
+    private Set<String> required = null;
     @OpenAPI30
     private String type = null;
     private Schema not = null;
@@ -1229,42 +1229,49 @@ public Schema minProperties(Integer minProperties) {
     }
 
     /**
-     * returns the required property from a Schema instance.
+     * Returns a copy of the required property from a Schema instance.
      *
-     * @return List&lt;String&gt; required
+     * <p>Note: the returned list is a snapshot copy of the internal set. Mutating
+     * the returned list (e.g. {@code schema.getRequired().add("x")}) does
+     * <em>not</em> modify this schema. Use {@link #addRequiredItem(String)} or
+     * {@link #setRequired(List)} to change the required fields.
+     *
+     * @return a new {@link List} containing the required field names, or {@code null} if none are set
      **/
 
     public List<String> getRequired() {
-        return required;
+        if (required == null) {
+            return null;
+        }
+        return new ArrayList<>(required);
     }
 
     public void setRequired(List<String> required) {
-        List<String> list = new ArrayList<>();
-        if (required != null) {
-            for (String req : required) {
-                if (this.properties == null || this.properties.containsKey(req)) {
-                    list.add(req);
-                }
-            }
+        if (required == null) {
+            this.required = null;
+            return;
         }
-        Collections.sort(list);
-        if (list.isEmpty()) {
-            list = null;
+        Set<String> set = new TreeSet<>();
+        for (String req : required) {
+            if (this.properties == null || this.properties.containsKey(req)) {
+                set.add(req);
+            }
         }
-        this.required = list;
+        this.required = set.isEmpty() ? null : set;
     }
 
     public Schema required(List<String> required) {
-        this.required = required;
+        this.setRequired(required);
         return this;
     }
 
     public Schema addRequiredItem(String requiredItem) {
-        if (this.required == null) {
-            this.required = new ArrayList<>();
+        if (this.properties == null || this.properties.containsKey(requiredItem)) {
+            if (this.required == null) {
+                this.required = new TreeSet<>();
+            }
+            this.required.add(requiredItem);
         }
-        this.required.add(requiredItem);
-        Collections.sort(required);
         return this;
     }
 

modules/swagger-models/src/test/java/io/swagger/v3/oas/models/media/SchemaTest.java

@@ -6,6 +6,7 @@
 import java.math.BigDecimal;
 import java.util.Arrays;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 
 public class SchemaTest {
@@ -178,4 +179,101 @@ private Schema<Object> createComplexSchema() {
         schema.setBooleanSchemaValue(true);
         return schema;
     }
+
+    @Test
+    public void testRequiredNoDuplicates() {
+        Schema<Object> schema = new Schema<>();
+        schema.addRequiredItem("id");
+        schema.addRequiredItem("name");
+        schema.addRequiredItem("id"); // duplicate
+
+        List<String> required = schema.getRequired();
+
+        // Duplicates should be removed
+        assertEquals(2, required.size());
+        assertTrue(required.contains("id"));
+        assertTrue(required.contains("name"));
+    }
+
+    @Test
+    public void testSetRequiredRemovesDuplicates() {
+        Schema<Object> schema = new Schema<>();
+        schema.setRequired(Arrays.asList("id", "name", "id", "email", "name"));
+
+        List<String> required = schema.getRequired();
+
+        // Should contain only unique values: id, name, email
+        assertEquals(3, required.size());
+    }
+
+
+    @Test
+    public void testRequiredIsSorted() {
+        Schema<Object> schema = new Schema<>();
+        schema.addRequiredItem("zebra");
+        schema.addRequiredItem("apple");
+        schema.addRequiredItem("mango");
+
+        List<String> required = schema.getRequired();
+
+        // Should be sorted alphabetically
+        assertEquals(Arrays.asList("apple", "mango", "zebra"), required);
+    }
+
+    @Test
+    public void testSetRequiredWithNull() {
+        Schema<Object> schema = new Schema<>();
+        schema.addRequiredItem("id");
+        schema.setRequired(null);
+
+        // Setting null should clear required
+        assertNull(schema.getRequired());
+    }
+
+    @Test
+    public void testSetRequiredWithEmptyList() {
+        Schema<Object> schema = new Schema<>();
+        schema.setRequired(Arrays.asList());
+
+        // Empty list should result in null
+        assertNull(schema.getRequired());
+    }
+
+    @Test
+    public void testAddRequiredItemIgnoresItemNotInProperties() {
+        Schema<Object> schema = new Schema<>();
+        Schema<String> nameSchema = new Schema<>();
+        schema.addProperty("name", nameSchema);
+
+        schema.addRequiredItem("name");       // exists in properties → accepted
+        schema.addRequiredItem("notAProp");   // not in properties → ignored
+
+        List<String> required = schema.getRequired();
+        assertEquals(1, required.size());
+        assertTrue(required.contains("name"));
+        assertFalse(required.contains("notAProp"));
+    }
+
+    @Test
+    public void testAddRequiredItemAcceptsAllWhenNoProperties() {
+        Schema<Object> schema = new Schema<>();
+        // no properties set → all items accepted
+        schema.addRequiredItem("id");
+        schema.addRequiredItem("name");
+
+        List<String> required = schema.getRequired();
+        assertEquals(2, required.size());
+    }
+
+    @Test
+    public void testGetRequiredReturnsCopy() {
+        Schema<Object> schema = new Schema<>();
+        schema.addRequiredItem("id");
+
+        List<String> copy = schema.getRequired();
+        copy.add("shouldNotAffectSchema");
+
+        // original schema should be unchanged
+        assertEquals(1, schema.getRequired().size());
+    }
 }