Skip to content

fix(normalizer): support OAS 3.1 annotated enums (oneOf + const) for consistent enum generation (C#) #23869

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nagabalaji-b wants to merge 19 commits into
base: master
Choose a base branch
from
+6,979 −10
Open

fix(normalizer): support OAS 3.1 annotated enums (oneOf + const) for consistent enum generation (C#) #23869

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
20cf96f
fix(csharp): use numeric .NET version check to prevent double URL-enc…
sagadira Apr 24, 2026
b443ae3
Merge pull request #172 from sagadira/CSCwu08056
vvb Apr 29, 2026
9fbf404
Introducing Annotated Enum with const
nagabalaji-b May 22, 2026
51e0b0f
fix: support OpenAPI 3.1 const in annotated enum normalization
nagabalaji-b May 25, 2026
ba6d6a2
fix(docs): use forward slashes in path separators for cross-platform …
nagabalaji-b May 25, 2026
553b721
revert: remove unrelated doc file changes from PR scope
nagabalaji-b May 26, 2026
3496c3b
refactor(normalizer): extract definesEnum variable per reviewer sugge…
nagabalaji-b May 26, 2026
55450c4
fix(normalizer): preserve x-enum-deprecated for oneOf/anyOf const enums
nagabalaji-b Jun 5, 2026
b45f152
Merge remote-tracking branch 'upstream/master' into openapitools-master
nagabalaji-b Jun 17, 2026
7c97781
chore: regenerate samples after normalization improvements
nagabalaji-b Jun 18, 2026
ed13261
chore(samples): normalize generated samples for cross-platform output
nagabalaji-b Jun 18, 2026
887cc11
Merge origin/master into openapitools-master (resolved conflicts)
nagabalaji-b Jun 19, 2026
6ef74e7
adding samples
nagabalaji-b Jun 19, 2026
41a9373
chore(csharp): sync HttpSigningConfiguration.mustache from upstream/m…
nagabalaji-b Jun 19, 2026
f183516
Revert "adding samples"
nagabalaji-b Jun 26, 2026
5e4b895
add annotated enum csharp config and regenerate samples
nagabalaji-b Jun 26, 2026
d35f8b2
Revert "add annotated enum csharp config and regenerate samples"
nagabalaji-b Jun 28, 2026
6978533
add csharp generichost annotated enum config
nagabalaji-b Jun 28, 2026
fe94074
regenerate samples for csharp generichost annotated enum
nagabalaji-b Jun 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/generators/fsharp-functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
|prependFormOrBodyParameters|Add form or body parameters to the beginning of the parameter list.| |false|
|sortModelPropertiesByRequiredFlag|Sort model properties to place required parameters before optional parameters.| |true|
|sortParamsByRequiredFlag|Sort method arguments to place required parameters before optional parameters.| |true|
|sourceFolder|source folder for generated code| |OpenAPI/src|
|sourceFolder|source folder for generated code| |OpenAPI\src|

@Mattias-Sehlstedt Mattias-Sehlstedt May 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are these path changes intentional?


## IMPORT MAPPING

Expand Down
2 changes: 1 addition & 1 deletion docs/generators/fsharp-giraffe-server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
|packageVersion|F# package version.| |1.0.0|
|returnICollection|Return ICollection<T> instead of the concrete type.| |false|
|sortParamsByRequiredFlag|Sort method arguments to place required parameters before optional parameters.| |true|
|sourceFolder|source folder for generated code| |OpenAPI/src|
|sourceFolder|source folder for generated code| |OpenAPI\src|
|useCollection|Deserialize array types to Collection<T> instead of List<T>.| |false|
|useDateTimeOffset|Use DateTimeOffset to model date-time properties| |false|
|useSwashbuckle|Uses the Swashbuckle.AspNetCore NuGet package for documentation.| |false|
Expand Down
2 changes: 1 addition & 1 deletion docs/generators/java-inflector.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
|snapshotVersion|Uses a SNAPSHOT version.|<dl><dt>**true**</dt><dd>Use a SnapShot Version</dd><dt>**false**</dt><dd>Use a Release Version</dd></dl>|null|
|sortModelPropertiesByRequiredFlag|Sort model properties to place required parameters before optional parameters.| |true|
|sortParamsByRequiredFlag|Sort method arguments to place required parameters before optional parameters.| |true|
|sourceFolder|source folder for generated code| |src/gen/java|
|sourceFolder|source folder for generated code| |src\gen\java|
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Outdated
|testOutput|Set output folder for models and APIs tests| |${project.build.directory}/generated-test-sources/openapi|
|useJakartaEe|whether to use Jakarta EE namespace instead of javax| |false|
|useOneOfInterfaces|whether to use a java interface to describe a set of oneOf options, where each option is a class that implements the interface| |false|
Expand Down
2 changes: 1 addition & 1 deletion docs/generators/jaxrs-cxf-client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
|snapshotVersion|Uses a SNAPSHOT version.|<dl><dt>**true**</dt><dd>Use a SnapShot Version</dd><dt>**false**</dt><dd>Use a Release Version</dd></dl>|null|
|sortModelPropertiesByRequiredFlag|Sort model properties to place required parameters before optional parameters.| |true|
|sortParamsByRequiredFlag|Sort method arguments to place required parameters before optional parameters.| |true|
|sourceFolder|source folder for generated code| |src/gen/java|
|sourceFolder|source folder for generated code| |src\gen\java|
|testOutput|Set output folder for models and APIs tests| |${project.build.directory}/generated-test-sources/openapi|
|useAbstractionForFiles|Use alternative types instead of java.io.File to allow passing bytes without a file on disk.| |false|
|useBeanValidation|Use BeanValidation API annotations| |false|
Expand Down
4 changes: 2 additions & 2 deletions docs/generators/swift5.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,13 +52,13 @@ These options may be applied as additional-properties (cli) or configOptions (pl
|responseAs|Optionally use libraries to manage response. Currently PromiseKit, RxSwift, Result, Combine, AsyncAwait are available.| |null|
|sortModelPropertiesByRequiredFlag|Sort model properties to place required parameters before optional parameters.| |true|
|sortParamsByRequiredFlag|Sort method arguments to place required parameters before optional parameters.| |true|
|swiftPackagePath|Set a custom source path instead of OpenAPIClient/Classes/OpenAPIs.| |null|
|swiftPackagePath|Set a custom source path instead of OpenAPIClient\Classes\OpenAPIs.| |null|
|swiftUseApiNamespace|Flag to make all the API classes inner-class of {{projectName}}API| |null|
|useBacktickEscapes|Escape reserved words using backticks (default: false)| |false|
|useClasses|Use final classes for models instead of structs (default: false)| |false|
|useCustomDateWithoutTime|Uses a custom type to decode and encode dates without time information to support OpenAPIs date format (default: false)| |false|
|useJsonEncodable|Make models conform to JSONEncodable protocol (default: true)| |true|
|useSPMFileStructure|Use SPM file structure and set the source path to Sources/{{projectName}} (default: false).| |null|
|useSPMFileStructure|Use SPM file structure and set the source path to Sources\{{projectName}} (default: false).| |null|
|validatable|Make validation rules and validator for model properties (default: true)| |true|

## IMPORT MAPPING
Expand Down
4 changes: 2 additions & 2 deletions docs/generators/swift6.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,13 +54,13 @@ These options may be applied as additional-properties (cli) or configOptions (pl
|responseAs|Optionally use libraries to manage response. Currently AsyncAwait, Combine, Result, RxSwift, ObjcBlock, PromiseKit are available.| |null|
|sortModelPropertiesByRequiredFlag|Sort model properties to place required parameters before optional parameters.| |true|
|sortParamsByRequiredFlag|Sort method arguments to place required parameters before optional parameters.| |true|
|swiftPackagePath|Set a custom source path instead of Sources/{{projectName}}.| |null|
|swiftPackagePath|Set a custom source path instead of Sources\{{projectName}}.| |null|
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Outdated
|swiftUseApiNamespace|Flag to make all the API classes inner-class of {{projectName}}API| |null|
|useBacktickEscapes|Escape reserved words using backticks (default: false)| |false|
|useClasses|Use final classes for models instead of structs (default: false)| |false|
|useCustomDateWithoutTime|Uses a custom type to decode and encode dates without time information to support OpenAPIs date format (default: false)| |false|
|useParameterConvertible|Make models conform to ParameterConvertible protocol (default: true)| |true|
|useSPMFileStructure|Use SPM file structure and set the source path to Sources/{{projectName}} (default: true).| |null|
|useSPMFileStructure|Use SPM file structure and set the source path to Sources\{{projectName}} (default: true).| |null|
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Outdated
|validatable|Make validation rules and validator for model properties (default: true)| |true|

## IMPORT MAPPING
Expand Down
15 changes: 10 additions & 5 deletions modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1620,10 +1620,15 @@ protected Schema simplifyComposedSchemaWithEnums(Schema schema, List<Object> sub

Schema subSchema = ModelUtils.getReferencedSchema(openAPI, (Schema) item);

// Check if this sub-schema has an enum (with one or more values)
if (subSchema.getEnum() == null || subSchema.getEnum().isEmpty()) {
// Check if this sub-schema has an enum or const value (OpenAPI 3.1 uses const for single-value enums)
List<Object> subSchemaEnumValues = subSchema.getEnum();
if ((subSchemaEnumValues == null || subSchemaEnumValues.isEmpty()) && subSchema.getConst() == null) {

@Mattias-Sehlstedt Mattias-Sehlstedt May 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rather than doing (subSchemaEnumValues == null || subSchemaEnumValues.isEmpty()) twice, could we extract this to a variable boolean definesEnum = ModelUtils.hasEnum(subSchema) and then have

if (!definesEnum && subSchema.getConst() == null) {

This could allow use to skip the comments almost entirely and instead allow the variable/method names be the explanation themselves.

return schema;
}
// If const is present but enum is not, treat const as a single enum value
if ((subSchemaEnumValues == null || subSchemaEnumValues.isEmpty()) && subSchema.getConst() != null) {
subSchemaEnumValues = Arrays.asList(subSchema.getConst());
}

// Ensure all sub-schemas have the same type (if type is specified)
if(subSchema.getTypes() != null && subSchema.getTypes().size() > 1) {
Expand All @@ -1639,17 +1644,17 @@ protected Schema simplifyComposedSchemaWithEnums(Schema schema, List<Object> sub
}
}
// Add all enum values from this sub-schema to our collection
if(subSchema.getEnum().size() == 1) {
if(subSchemaEnumValues.size() == 1) {
String description = subSchema.getTitle() == null ? "" : subSchema.getTitle();
if(subSchema.getDescription() != null) {
if(!description.isEmpty()) {
description += " - ";
}
description += subSchema.getDescription();
}
enumValues.put(subSchema.getEnum().get(0), description);
enumValues.put(subSchemaEnumValues.get(0), description);
} else {
for(Object e: subSchema.getEnum()) {
for(Object e: subSchemaEnumValues) {
enumValues.put(e, "");
}
}
Expand Down
7 changes: 4 additions & 3 deletions modules/openapi-generator/src/test/java/org/openapitools/codegen/OpenAPINormalizerTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1536,9 +1536,10 @@ public void testOpenAPINormalizerSimplifyOneOfAnyOf31Spec() {
assertEquals(schema14.getType(), null);

Schema schema16 = openAPI.getComponents().getSchemas().get("TypeIntegerWithOneOf");
assertEquals(schema16.getOneOf().size(),3);
assertEquals(((Schema) schema16.getOneOf().get(0)).getConst(), 1);
assertEquals(((Schema) schema16.getOneOf().get(0)).getDeprecated(), true);
// After normalization, oneOf with const values should be simplified to enum
assertEquals(schema16.getOneOf(), null);
assertEquals(schema16.getEnum().size(), 3);
assertEquals(schema16.getEnum().get(0), 1);

@JPPortier JPPortier May 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(I'm not repo maintainer but the PR is something I was thinking about myself: so thank you)

The test against deprecated (https://github.com/nagabalaji-b/openapi-generator/blob/3496c3b7cffbc0cdc728cc77bd64708b8ba6ae9a/modules/openapi-generator/src/test/resources/3_1/simplifyOneOfAnyOf_test.yaml#L133) is lost here (and the information from schema too)

Here, seems it is not possible with current enum support implementation ("simple" list of values and optional list of descriptions with x-enum-descriptions) to support enum as "schema" enabling to keep all "schemas" related information with no loss.

@wing328 wing328 Jun 5, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nagabalaji-b can you please take a look and add back the deprecated test?

@nagabalaji-b nagabalaji-b Jun 5, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@wing328 Done. I added back the deprecated test coverage:

Code change: Modified simplifyComposedSchemaWithEnums() to collect and preserve per-value deprecated flags from OAS 3.1 oneOf/anyOf + const sub-schemas into x-enum-deprecated extension.

Test assertion: Added explicit checks in testOpenAPINormalizerSimplifyOneOfAnyOf31Spec() for TypeIntegerWithOneOf schema:

Verifies x-enum-deprecated list size = 3
Verifies flags match expected values: [true, false, false] (first enum value was deprecated in the original YAML)
Validation: Ran the test locally and confirmed BUILD SUCCESS.

The deprecated metadata from the annotated enum pattern (oneOf + const) is now preserved through normalization, so generators can access it via the x-enum-deprecated extension.


Schema schema18 = openAPI.getComponents().getSchemas().get("OneOfNullAndRef3");
// original oneOf removed and simplified to just $ref (oneOf sub-schema) instead
Expand Down