OpenAPI: String names from enum in schema for enum attributes
Opened this issue · 8 comments
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.
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.
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?
Here an enum is serialized with names: https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/master/test/OpenApiTests/LegacyOpenApi/GeneratedSwagger/swagger.g.json#L6030
According to microsoft/kiota#90, kiota looks for x-ms-enum, which is described at https://azure.github.io/autorest/extensions/#x-ms-enum.
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.
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.
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.
I see. So mabye this is a wait and see thing for now.