Feature/add kotlin enum unknown default case support

docs/generators/kotlin-spring.md

@@ -32,6 +32,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |delegatePattern|Whether to generate the server files using the delegate pattern| |false|
 |documentationProvider|Select the OpenAPI documentation provider.|<dl><dt>**none**</dt><dd>Do not publish an OpenAPI specification.</dd><dt>**source**</dt><dd>Publish the original input OpenAPI specification.</dd><dt>**springdoc**</dt><dd>Generate an OpenAPI 3 specification using SpringDoc.</dd></dl>|springdoc|
 |enumPropertyNaming|Naming convention for enum properties: 'camelCase', 'PascalCase', 'snake_case', 'UPPERCASE', 'original', and 'bestEffortBacktick' (like 'original' but tries to wrap values in backticks before falling back to sanitizing, e.g. `name,asc` stays `name,asc` rather than becoming nameCommaAsc; useful for sort/order enums)| |original|
+|enumUnknownDefaultCase|If the server adds new enum cases, that are unknown by an old spec/client, the client will fail to parse the network response.With this option enabled, each enum will have a new case, 'unknown_default_open_api', so that when the server sends an enum case that is not known by the client/spec, they can safely fallback to this case.| |false|
 |exceptionHandler|generate default global exception handlers (not compatible with reactive. enabling reactive will disable exceptionHandler )| |true|
 |generatePageableConstraintValidation|Generate a @ValidPageable annotation and PageableConstraintValidator class, and apply @ValidPageable to the injected Pageable parameter of operations whose 'page' or 'size' parameter specifies a maximum constraint. The annotation enforces those constraints on the Pageable object that replaces the individual page/size query parameters. Requires useBeanValidation=true and library=spring-boot.| |false|
 |generateSortValidation|Generate a @ValidSort annotation and SortValidator class, and apply @ValidSort to the injected Pageable parameter of operations whose 'sort' parameter has enum values. The annotation validates that sort values in the Pageable object match the allowed enum values from the spec. Requires useBeanValidation=true and library=spring-boot.| |false|

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/KotlinSpringServerCodegen.java

@@ -311,6 +311,8 @@ public KotlinSpringServerCodegen() {
         addSwitch(COMPANION_OBJECT, "Whether to generate companion objects in data classes, enabling companion extensions.", companionObject);
         addSwitch(SUSPEND_FUNCTIONS, "Whether to generate suspend functions for API operations. Useful for Spring MVC with Kotlin coroutines without requiring the full reactive stack.", suspendFunctions);
         cliOptions.add(CliOption.newBoolean(CodegenConstants.USE_DEDUCTION_FOR_ONE_OF_INTERFACES, CodegenConstants.USE_DEDUCTION_FOR_ONE_OF_INTERFACES_DESC, useDeductionForOneOfInterfaces));
+        cliOptions.add(CliOption.newBoolean(CodegenConstants.ENUM_UNKNOWN_DEFAULT_CASE, CodegenConstants.ENUM_UNKNOWN_DEFAULT_CASE_DESC).defaultValue("false"));
+
         addSwitch(CodegenConstants.USE_ENUM_VALUE_INTERFACE, CodegenConstants.USE_ENUM_VALUE_INTERFACE_DESC, useEnumValueInterface);
         addSwitch(CodegenConstants.OPENAPI_NULLABLE,
                 "Enable OpenAPI Jackson Nullable library (jackson-databind-nullable) for optional + nullable "
@@ -659,6 +661,11 @@ public void processOpts() {
         }
         writePropertyBack(SKIP_DEFAULT_INTERFACE, skipDefaultInterface);
 
+
+        if (additionalProperties.containsKey(CodegenConstants.ENUM_UNKNOWN_DEFAULT_CASE)) {
+            setEnumUnknownDefaultCase(Boolean.parseBoolean(additionalProperties.get(CodegenConstants.ENUM_UNKNOWN_DEFAULT_CASE).toString()));
+        }
+
         if (additionalProperties.containsKey(REACTIVE)) {
             if (SPRING_CLOUD_LIBRARY.equals(library)) {
                 throw new IllegalArgumentException("Currently, reactive option doesn't supported by Spring Cloud");

modules/openapi-generator/src/main/resources/kotlin-spring/dataClass.mustache

@@ -50,14 +50,15 @@
     */
     enum class {{{nameInPascalCase}}}(@get:JsonValue {{#useEnumValueInterface}}{{^isContainer}}override {{/isContainer}}{{/useEnumValueInterface}}val value: {{#isContainer}}{{#items}}{{{dataType}}}{{/items}}{{/isContainer}}{{^isContainer}}{{{dataType}}}{{/isContainer}}) {{#vendorExtensions.x-kotlin-implements}}{{#-first}}: {{{.}}}{{/-first}}{{^-first}}, {{{.}}}{{/-first}} {{/vendorExtensions.x-kotlin-implements}}{
 {{#allowableValues}}{{#enumVars}}
-        {{{name}}}({{{value}}}){{^-last}},{{/-last}}{{/enumVars}}{{/allowableValues}};
+        {{{name}}}({{{value}}}){{^-last}},{{/-last}}{{/enumVars}}{{/allowableValues}}{{#enumUnknownDefaultCase}},
+        UNKNOWN_DEFAULT_OPEN_API({{#isString}}"unknown_default_open_api"{{/isString}}{{^isString}}{{#dataType}}null{{/dataType}}{{/isString}}){{/enumUnknownDefaultCase}};
 
         companion object {
             @JvmStatic
             @JsonCreator
             fun forValue(value: {{#isContainer}}{{#items}}{{{dataType}}}{{/items}}{{/isContainer}}{{^isContainer}}{{{dataType}}}{{/isContainer}}): {{{nameInPascalCase}}} {
                 return values().firstOrNull{it -> it.value == value}
-                    ?: throw IllegalArgumentException("Unexpected value '$value' for enum '{{nameInPascalCase}}'")
+                    {{^enumUnknownDefaultCase}}?: throw IllegalArgumentException("Unexpected value '$value' for enum '{{nameInPascalCase}}'"){{/enumUnknownDefaultCase}}{{#enumUnknownDefaultCase}}?: UNKNOWN_DEFAULT_OPEN_API{{/enumUnknownDefaultCase}}
             }
         }
     }

modules/openapi-generator/src/main/resources/kotlin-spring/enumClass.mustache

@@ -1,17 +1,30 @@
 /**
-* {{{description}}}
-* Values: {{#allowableValues}}{{#enumVars}}{{&name}}{{^-last}},{{/-last}}{{/enumVars}}{{/allowableValues}}
-*/
-enum class {{classname}}(@get:JsonValue {{#useEnumValueInterface}}override {{/useEnumValueInterface}}val value: {{dataType}}) {{#vendorExtensions.x-kotlin-implements}}{{#-first}}: {{{.}}}{{/-first}}{{^-first}}, {{{.}}}{{/-first}} {{/vendorExtensions.x-kotlin-implements}}{
+ * {{{description}}}
+ * Values: {{#allowableValues}}{{#enumVars}}{{&name}}{{^-last}},{{/-last}}{{/enumVars}}{{/allowableValues}}
+ */
+enum class {{classname}}(
+    @get:JsonValue {{#useEnumValueInterface}}override {{/useEnumValueInterface}}val value: {{dataType}}
+) {{#vendorExtensions.x-kotlin-implements}}{{#-first}}: {{{.}}}{{/-first}}{{^-first}}, {{{.}}}{{/-first}}{{/vendorExtensions.x-kotlin-implements}} {
+
 {{#allowableValues}}{{#enumVars}}
-    {{&name}}({{{value}}}){{^-last}},{{/-last}}{{/enumVars}}{{/allowableValues}};
+    {{&name}}({{{value}}}){{^-last}},{{/-last}}{{/enumVars}}{{/allowableValues}}
+{{#enumUnknownDefaultCase}},
+    UNKNOWN_DEFAULT_OPEN_API({{#isString}}"unknown_default_open_api"{{/isString}}{{^isString}}{{#dataType}}null{{/dataType}}{{/isString}})
+{{/enumUnknownDefaultCase}};
 
     companion object {
         @JvmStatic
         @JsonCreator
         fun forValue(value: {{dataType}}): {{classname}} {
-                return values().firstOrNull{it -> it.value == value}
-                    ?: throw IllegalArgumentException("Unexpected value '$value' for enum '{{classname}}'")
+            return values().firstOrNull { it.value == value }
+{{#enumUnknownDefaultCase}}
+                ?: UNKNOWN_DEFAULT_OPEN_API
+{{/enumUnknownDefaultCase}}
+{{^enumUnknownDefaultCase}}
+                ?: throw IllegalArgumentException(
+                    "Unexpected value '$value' for enum '{{classname}}'"
+                )
+{{/enumUnknownDefaultCase}}
         }
     }
 }

modules/openapi-generator/src/test/java/org/openapitools/codegen/kotlin/spring/KotlinSpringServerCodegenTest.java

@@ -6678,4 +6678,132 @@ public void schemaMappingWithNullableAllOfRendersNullableKotlinProperty() throws
         String content = Files.readString(myObjectFile.toPath());
         assertThat(content).contains("com.example.ExternalModel?");
     }
+
+     @Test(description = "test enumUnknownDefaultCase option")
+    public void testEnumUnknownDefaultCaseOption() {
+        final KotlinSpringServerCodegen codegen = new KotlinSpringServerCodegen();
+
+        // Test default value is false
+        codegen.processOpts();
+        Assert.assertEquals(codegen.getEnumUnknownDefaultCase(), Boolean.FALSE);
+
+        // Test setting via additionalProperties
+        codegen.additionalProperties().put(CodegenConstants.ENUM_UNKNOWN_DEFAULT_CASE, "true");
+        codegen.processOpts();
+        Assert.assertEquals(codegen.getEnumUnknownDefaultCase(), Boolean.TRUE);
+    }
+
+    @Test(description = "test enum model generation with enumUnknownDefaultCase")
+    public void testEnumModelWithUnknownDefaultCase() {
+        final OpenAPI openAPI = TestUtils.parseFlattenSpec("src/test/resources/3_1/enum_unknown_default_case.yaml");
+        final KotlinSpringServerCodegen codegen = new KotlinSpringServerCodegen();
+
+        // Enable enumUnknownDefaultCase
+        codegen.additionalProperties().put(CodegenConstants.ENUM_UNKNOWN_DEFAULT_CASE, "true");
+        codegen.setOpenAPI(openAPI);
+        codegen.processOpts();
+
+        // Verify that enumUnknownDefaultCase is set
+        Assert.assertEquals(codegen.getEnumUnknownDefaultCase(), Boolean.TRUE);
+
+        // Process all models to trigger enum processing
+        Map<String, Schema> schemas = openAPI.getComponents().getSchemas();
+        Map<String, ModelsMap> allModels = new HashMap<>();
+        for (String modelName : schemas.keySet()) {
+            Schema schema = schemas.get(modelName);
+            CodegenModel cm = codegen.fromModel(modelName, schema);
+            ModelsMap modelsMap = new ModelsMap();
+            modelsMap.setModels(Collections.singletonList(new ModelMap(Collections.singletonMap("model", cm))));
+            allModels.put(modelName, modelsMap);
+        }
+
+        // Post-process to add enumVars
+        allModels = codegen.postProcessAllModels(allModels);
+
+        // Get the ColorEnum model
+        CodegenModel colorEnum = null;
+        for (Map.Entry<String, ModelsMap> entry : allModels.entrySet()) {
+            if ("ColorEnum".equals(entry.getKey())) {
+                colorEnum = entry.getValue().getModels().get(0).getModel();
+                break;
+            }
+        }
+
+        Assert.assertNotNull(colorEnum);
+        Assert.assertNotNull(colorEnum.allowableValues);
+
+        List<Map<String, Object>> enumVars = (List<Map<String, Object>>) colorEnum.allowableValues.get("enumVars");
+        Assert.assertNotNull(enumVars);
+
+        // Check that we have the expected enum values including UNKNOWN_DEFAULT_OPEN_API
+        Assert.assertTrue(enumVars.stream().anyMatch(var -> "'RED'".equals(var.get("value"))));
+        Assert.assertTrue(enumVars.stream().anyMatch(var -> "'GREEN'".equals(var.get("value"))));
+        Assert.assertTrue(enumVars.stream().anyMatch(var -> "'BLUE'".equals(var.get("value"))));
+        Assert.assertTrue(enumVars.stream().anyMatch(var -> "'YELLOW'".equals(var.get("value"))));
+        Assert.assertTrue(enumVars.stream().anyMatch(var -> "'unknown_default_open_api'".equals(var.get("value"))));
+    }
+
+    @Test(description = "test enum generation with enumUnknownDefaultCase enabled")
+    public void testEnumGenerationWithUnknownDefaultCase() throws IOException {
+        File output = Files.createTempDirectory("test").toFile().getCanonicalFile();
+        output.deleteOnExit();
+        String outputPath = output.getAbsolutePath().replace('\\', '/');
+
+        final CodegenConfigurator configurator = new CodegenConfigurator()
+                .setGeneratorName("kotlin-spring")
+                .setInputSpec("src/test/resources/3_1/enum_unknown_default_case.yaml")
+                .setOutputDir(outputPath)
+                .addAdditionalProperty(CodegenConstants.ENUM_UNKNOWN_DEFAULT_CASE, "true");
+
+        DefaultGenerator generator = new DefaultGenerator();
+        List<File> files = generator.opts(configurator.toClientOptInput()).generate();
+        files.forEach(File::deleteOnExit);
+
+        Path enumFile = Paths.get(outputPath,
+                "src",        
+                "main",         
+                "kotlin",        
+                "org",         
+                "openapitools",         
+                "model",
+                "Color.kt"
+        );
+
+        TestUtils.assertFileContains(enumFile,
+                "UNKNOWN_DEFAULT_OPEN_API");
+
+        TestUtils.assertFileContains(enumFile,
+                "?: UNKNOWN_DEFAULT_OPEN_API");
+}
+
+    @Test(description = "test enum generation with enumUnknownDefaultCase disabled")
+    public void testEnumGenerationWithoutUnknownDefaultCase() throws IOException {
+        File output = Files.createTempDirectory("test").toFile().getCanonicalFile();
+        output.deleteOnExit();
+        String outputPath = output.getAbsolutePath().replace('\\', '/');
+
+        final CodegenConfigurator configurator = new CodegenConfigurator()
+                .setGeneratorName("kotlin-spring")
+                .setInputSpec("src/test/resources/3_1/enum_unknown_default_case.yaml")
+                .setOutputDir(outputPath)
+                .addAdditionalProperty(CodegenConstants.ENUM_UNKNOWN_DEFAULT_CASE, "false");
+
+        DefaultGenerator generator = new DefaultGenerator();
+        List<File> files = generator.opts(configurator.toClientOptInput()).generate();
+        files.forEach(File::deleteOnExit);
+
+        Path enumFile = Paths.get(outputPath,
+                "src",        
+                "main",         
+                "kotlin",        
+                "org",         
+                "openapitools",         
+                "model",
+                "Color.kt"
+        );
+
+        // Check that UNKNOWN_DEFAULT_OPEN_API is NOT added
+        TestUtils.assertFileNotContains(enumFile, "UNKNOWN_DEFAULT_OPEN_API");
+
+    }
 }

modules/openapi-generator/src/test/resources/3_1/enum_unknown_default_case.yaml

@@ -0,0 +1,56 @@
+openapi: 3.0.0
+info:
+  title: Enum Test API
+  description: API for testing enum generation with enumUnknownDefaultCase
+  version: 1.0.0
+paths:
+  /colors:
+    get:
+      summary: Get color
+      operationId: getColor
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ColorResponse'
+components:
+  schemas:
+    ColorResponse:
+      type: object
+      required:
+        - color
+        - status
+      properties:
+        color:
+          $ref: '#/components/schemas/ColorEnum'
+        status:
+          $ref: '#/components/schemas/StatusEnum'
+        priority:
+          $ref: '#/components/schemas/PriorityEnum'
+    ColorEnum:
+      type: string
+      description: Available colors
+      enum:
+        - RED
+        - GREEN
+        - BLUE
+        - YELLOW
+    StatusEnum:
+      type: string
+      description: Status values
+      enum:
+        - PENDING
+        - APPROVED
+        - REJECTED
+        - IN_PROGRESS
+    PriorityEnum:
+      type: integer
+      description: Priority levels
+      enum:
+        - 1
+        - 2
+        - 3
+        - 4
+        - 5