Enum Best Practices

[savitmk]

I did a dive into OpenAPI's support for Enums, and it appears there's no mainline support until 3.1 will introduce a new feature which should handle this use case.

In the meantime, and specifically for this library, what is the suggested method for handling enums? At a basic level, being able to "name" enum values would be great.

In the documentation and code, I know that Choices two-tuples are supported, but only the keys are read, and the labels are ignored. Would it be possible to include the names in the output somehow? Would it be possible to integrate an OpenAPI extension into the schema and the default Swagger/Redoc display?

As it stands, as a result of my investigation, I include a Markdown help_text= argument to the fields that use my enums. This works out well enough - but I am curious if there isn't a better way.

Thanks!!!

[tfranzel]

drf-spectacular is currently based on OpenAPI 3.0.3. currently i see no good way to model the tuples into the schema. for now i think the generated Enum "components" are the best we can do for now. it is not perfect, but works well enough imho. with 3.1 we might accommodate your request.

[savitmk]

thanks, and understood.

follow up: is there a way to include manual documentation with the components? and by that I specifically mean the "Schemas" section at the bottom of swagger-ui: it's not very helpful to have MyEnum: [1, 2, 3].

[tfranzel]

the serializers are translated into components. you have help_text and the serializer docstring available there.

for the implicitly generated components (enums), there is currently no way to pass through that information. expressive names are the best you can do. if the generated enum name are not good enough you can override the name in the settings.

[savitmk]

got it, thanks @tfranzel !