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

[nagabalaji-b]

Summary

This PR addresses normalization for OpenAPI 3.1 annotated enums, where enum values are expressed using oneOf + const. The main focus is on ensuring C# behavior aligns with traditional enum handling.

Problem

OpenAPI 3.0 typically utilizes enum arrays. In contrast, OpenAPI 3.1 often adopts an annotated enum style with oneOf + const and per-value descriptions. Prior to this fix, const-based composed schemas were not consistently simplified into enum-like schemas, potentially impacting strong enum generation in C#.

Example (OAS 3.1)

StatusType:
type: string
oneOf:
- const: ""
description: Unknown status
- const: ACTIVE
description: Active status
- const: INACTIVE
description: Inactive status
default: ""
x-omitempty: true

Equivalent OAS 3.0 Shape

StatusType:
type: string
enum:
- ""
- ACTIVE
- INACTIVE
default: ""
x-omitempty: true

C# Before vs After

Before Fix (String Property)

[DataMember(Name = "statusType", EmitDefaultValue = true)]
public string StatusType { get; set; }

private string _statusType;
private bool _flagStatusType;

The property is a plain string because oneOf + const was not normalized to enum semantics.

After Fix (Strong Enum)

[JsonConverter(typeof(StringEnumConverter))]
public enum StatusTypeEnum
{
/// /// Enum Empty for value: 
/// [EnumMember(Value = "")]
Empty = 1,

/// /// Enum ACTIVE for value: ACTIVE
/// [EnumMember(Value = "ACTIVE")]
ACTIVE = 2,

/// /// Enum INACTIVE for value: INACTIVE
/// [EnumMember(Value = "INACTIVE")]
INACTIVE = 3
}

[DataMember(Name = "statusType", EmitDefaultValue = true)]
public StatusTypeEnum? StatusType { get; set; }

After normalization, the schema is recognized as an enum and generates a strongly-typed enum with the appropriate JSON converter and member attributes.

Actual Behavior Before

OAS 3.1 oneOf + const was not consistently normalized to enum semantics. C# output could revert to non-enum-style modeling for this pattern.

Expected Behavior

OAS 3.1 oneOf + const should normalize in the same manner as OAS 3.0 enums. C# should consistently produce strongly typed enum output.

Changes in This PR

• Treat const as a single enum value when an enum is absent in composed sub-schemas.
• Apply composed enum simplification consistently for oneOf and anyOf enum-like paths.
• Update OAS 3.1 normalizer test expectations for the new normalized shape.
• Regenerate samples and documentation for the generator.

C# Result After Fix (Illustrative)

[JsonConverter(typeof(StringEnumConverter))]
public enum ComponentTypeEnum
{
/// /// Enum Empty for value: 
/// [EnumMember(Value = "")]
Empty = 1,

/// /// Enum CORE for value: CORE
/// [EnumMember(Value = "CORE")]
CORE = 2,

/// /// Enum EDGE for value: EDGE
/// [EnumMember(Value = "EDGE")]
EDGE = 3
}

public class SampleModel
{
[DataMember(Name = "componentType", EmitDefaultValue = true)]
public ComponentTypeEnum? ComponentType { get; set; }
}

Validation

The targeted normalizer test for OAS 3.1 simplifying oneOf/anyOf paths passed. Samples have been regenerated for Java configurations. Documentation for the generator has been exported.

Compatibility

This is a bug fix only. No intended breaking behavior changes. The normalization improvement is generator-agnostic; C# is the primary verified use case.

PR Checklist

• Read the contribution guidelines.
• The Pull Request title clearly describes the work in the pull request, and the Pull Request description provides details on how to validate the work. Missing information here may result in a delayed response from the community.
• Run the following commands to build the project and update samples:

./mvnw clean package -DskipTests
./bin/generate-samples.sh bin/configs/csharp-restsharp*.yaml bin/configs/csharp-httpclient*.yaml
./bin/utils/export_docs_generators.sh

• File the PR against the correct branch: master.
• If your PR targets a specific programming language, @mention the technical committee members for that language:
  @muttleyxd @devhl-labs @lucasheim @shibayan (C# generators)

---

Summary by cubic

Normalize OpenAPI 3.1 annotated enums (oneOf + const) as true enums. This ensures that C# code generation produces strong enums consistently, matching OAS 3.0 behavior.

• Bug Fixes
• Treat const as a single enum value when an enum is missing in sub-schemas.
• Collapse oneOf/anyOf enum-like schemas into a single enum in the parent, preserving types and per-value descriptions.
• Update tests to expect enums after normalization; regenerate documentation and samples.
  Written for commit 51e0b0f. Summary will update with new commits. Review in cubic

[cubic-dev-ai]

3 issues found across 8 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[Mattias-Sehlstedt]

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.

[Mattias-Sehlstedt]

Are these path changes intentional?

[Mattias-Sehlstedt]

Thanks for adjusting to the suggestions. 👍

I am not a maintainer of the project, so I cannot make a formal review with an approve.

[JPPortier]

(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]

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

[nagabalaji-b]

@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.