Microsoft.AspNetCore.OpenApi should support annotated enumerations.
- Dominant language
- C#
- Stars
- 38.4k
- Forks
- 10.9k
- Avg merge
- 2d 5h
- Merged PRs (30d)
- 276
Description
### Is there an existing issue for this?
- [x] I have searched the existing issues
### Is your feature request related to a problem? Please describe the problem.
Currently, as described in [this document](https://learn.microsoft.com/aspnet/core/fundamentals/openapi/include-metadata?view=aspnetcore-10.0&tabs=minimal-apis#enum), if enums are not transformed into strings, they are extracted as simple types. (https://github.com/dotnet/aspnetcore/issues/58230)
Example:
```csharp
[Description("Enum Description")]
public enum EnumType
{
[Description("ValueA Description")]
A = 1,
[Description("ValueB Description")]
B = 2
}
```
```json
"enumType": {
"type": "integer",
"enum": [1, 2],
"description": "Enum Description"
}
```
### Describe the solution you'd like
Starting from OpenAPI 3.1.1, it is proposed to implement annotated enums using `oneOf` + `anyOf` + `const` + `title` + `description`. (https://spec.openapis.org/oas/v3.1.1.html#annotated-enumerations)
This was already suggested in https://github.com/dotnet/aspnetcore/issues/58239, but was postponed due to the lack of OpenAPI 3.1 support in `Microsoft.OpenApi`.
> Supporting OpenAPI v3.1 is a long-term goal of this effort. However, we're limited by the fact that the underlying OpenAPI library we use (https://github.com/microsoft/openapi.net) doesn't support OpenAPI v3.1 yet.
>
> They are in the process of adding that support in a new major version of the package that we intend on upgrading to consume these new APIs when those updates are released.
Now that `Microsoft.OpenApi` has added support for OpenAPI 3.1+ (up to 3.2.0), annotated enums would be a more appropriate approach instead of exposing enums as plain primitive types without metadata.
Example:
```json
{
"type": "integer",
"oneOf": [
{"const": 1, "title": "A", "description": "ValueA Description"},
{"const": 2, "title": "B", "description": "ValueB Description"}
],
"description": "Enum Description"
}
```
### Additional context
Although the proposal (https://spec.openapis.org/oas/v3.1.1.html#annotated-enumerations) is only a recommendation, it is still a more appropriate standard approach compared to extracting no information for enums, and therefore worth implementing.
There has been demand for this feature in the past, as seen in proposals such as `x-enumNames` or `x-enum-var-names`.
(https://github.com/dotnet/aspnetcore/issues/62968, https://github.com/dotnet/aspnetcore/issues/63223, https://github.com/dotnet/aspnetcore/issues/65610)
Since those were rejected for being non-standard, it would be desirable to adopt the standardized approach instead.
Contributor guide
Assessment
This issue has not been assessed yet.