OpenAPI: String names from enum in schema for enum attributes

[bjornharrtell]

If one use an enum as attribute openapi generation will create a schema with the integer ids of the enum values. It would be great if it could also include the string names and possibly even description attributes as x-enum-varnames and/or x-enum-descriptions.

[bjornharrtell]

See https://github.com/ferdikoomen/openapi-typescript-codegen/wiki/Enum-with-custom-names-and-descriptions, https://openapi-ts.dev/advanced and https://mykeels.medium.com/enums-mappings-in-openapi-a76be95fec07 for reference on the mentioned openapi extension fields.

[bkoelman]

Thanks for trying the preview and reporting back. It's already possible to serialize as strings. Did you add the last line from https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/master/test/OpenApiTests/LegacyOpenApi/LegacyStartup.cs?

I don't remember enum description handling, but https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/master/test/OpenApiTests/OpenApiStartup.cs#L28 might do the trick. If not, I'm open to support extensions like you mentioned. Have you tried if NSwag and Kiota understand them?

[bkoelman]

Here an enum is serialized with names: https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/master/test/OpenApiTests/LegacyOpenApi/GeneratedSwagger/swagger.g.json#L6030

[bkoelman]

According to microsoft/kiota#90, kiota looks for x-ms-enum, which is described at https://azure.github.io/autorest/extensions/#x-ms-enum.

[bkoelman]

Seems that Swashbuckle doesn't support doc-comments on enum members, according to domaindrivendev/Swashbuckle.WebApi#1290. There it is mentioned the problem can be worked around with a custom schema filter.

[bjornharrtell]

I'm happy with serializing the id in json-api responses / documents, in this case, but want to describe those ids in openapi schema (for consumers of the api). I'm not sure if x-ms-enum is intended for that... I haven't tried getting any tooling to actually use x-enum-varnames and/or x-enum-descriptions, this was just something I stumbled upon when making an experimental api (as recreation of an older semi-json-api api).

Lengthy discussion about something similar at RicoSuter/NSwag#1993 though.

And I can see some custom swagger gen document filter in here - https://stackoverflow.com/questions/36452468/swagger-ui-web-api-documentation-present-enums-as-strings that does something along what I would like but just as a plain presentation string which.

Seems strange to me that openapi haven't standardised a way to describe enum values as something more than an ordered list of numbers of strings.

[bkoelman]

Yeah, this is one of those gaps in the OpenAPI spec. At least a way is provided in the OpenAPI v3.1 spec: https://spec.openapis.org/oas/v3.1.1.html#x4-8-24-6-4-model-with-annotated-enumeration.

[bjornharrtell]

I see. So mabye this is a wait and see thing for now.