search

tfranzel / drf-spectacular

Sane and flexible OpenAPI 3 schema generation for Django REST framework.
https://drf-spectacular.readthedocs.io
BSD 3-Clause "New" or "Revised" License
2.31k stars 258 forks source link

Show Enum label in schema #337

Open krzysieqq opened 3 years ago

krzysieqq commented 3 years ago

Hi, Is there any easy way to show the enum label in the schema. I'm using Django 3+ which allow to declarate choices as enums with label as human-readable form (https://docs.djangoproject.com/en/3.1/ref/models/fields/#enumeration-types). I'd like to show label in schema and swagger UI for easier user choice. Is there any easy option to show this in swagger UI?

tfranzel commented 3 years ago

there is no concept for choice labels in OpenAPI. the only thing one could do is generating a description that contains all the choice label tuples. certainly an option.

krzysieqq commented 3 years ago

Ok, I see that there is issue for that in openApi https://github.com/OAI/OpenAPI-Specification/issues/681

tfranzel commented 3 years ago

ahh i see. thanks for the research. we could hack together a description string but i would prefer not to.

regarding the solutions in OAI/OpenAPI-Specification#681: we should wait until some kind of extension/vocabulary support emerges in swagger UI or redoc. its easy for us to add this, but if there is no support we gain nothing at the moment.

bahag-raesenerm commented 2 years ago

Hey everybody, trying my luck to hook here in. Is there any suggested solution yet? it seems from OpenAPI spec there is the following recommendation:

codeGen: namedEnum
oneOf:
  - const: 1
    title: Sunny
    description: Blue sky
  - const: 2
    title: Cloudy
    description: Slightly overcast
  - const: 3
    title: Rainy
    description: Take an umbrella with you

see https://github.com/OAI/OpenAPI-Specification/issues/681#issuecomment-1084952860

any hints appreciated

tfranzel commented 2 years ago

That looks promising. However, not much use implementing it until at least swagger-ui and openapi-codegen follow suit.

bahag-raesenerm commented 2 years ago

well, at least the code generators could work with it even before UI is adopted - but sure, I of course agree. any way to hook them in somewhere? ... or will they "just follow" the openApi spec then?

also, if drf-spectacular could be fastest to implement this ... could maybe motivate the others? :)

anyways, let me know in case I could support this somehow.

robin24 commented 1 year ago

I found this after being faced with the same problem, building my first ever API using DRF and Spectacular. This has several endpoints with enums as return value which can also be used to query the API, and I need a clean way of documenting that stuff.

Has there been any movement on this since the last comment here from 9 months ago? Thanks, really hope there's a solution to this by now :-).

tfranzel commented 1 year ago

Has there been any movement on this since the last comment here from 9 months ago?

@robin24 Well it is not that we don't want to support it, it is just pointless when our counterparts have no support yet.

also, if drf-spectacular could be fastest to implement this ... could maybe motivate the others? :)

@bahag-raesenerm That wishful thinking made me chuckle for a moment. Sadly, this not how that works.

When this was originally written, it seemed like OpenAPI 3.1 isn't too far around the corner. With hindsight we now know that 3.1 support has picked up very slowly and the ecosystem still has only very limited support.

I simply assumed this whole thing is not worth the hassle, given that 3.1 is just right around the corner. This has been proven quite false. I already had a prototype laying around for this, but didn't follow through with it.

Today, I would say it is worth the complication, given that it might take another year or two for proper 3.1 (ecosystem) support. Will add the 3.0.3 "description" solution back onto the roadmap. Depending on how the 3.1 solution is supported, we may add support at a later stage.

robin24 commented 1 year ago

@tfranzel Thanks so much for your response! Just to clarify, when asking about whether there had been any movement within the last 9 months, I actually wanted to know whether there had been any developments throughout the ecosystem paving the way to support this. It wasn't meant to come across as criticism of Spectacular or the hard work that you've been putting into it, although after reading my previous post again I see how it could've been perceived as such for which I'd like to sincerely apologize.

As I said, this is my first time building a Restful API, and so I just don't know all the moving parts that need to fall into place before a change like this can be made. Many thanks for helping me better understand this with your above explanations, I'd love to see the ball get rolling on this but I understand it will take some time.

tfranzel commented 1 year ago

if anyone is interested, please review #952. It is not the solution for 3.1.0 mentioned in https://github.com/tfranzel/drf-spectacular/issues/337#issuecomment-1114549682 though.

This injects the same information into the description, making this compatible with all existing tooling. God knows when above 3.1 feature will be properly supported by the ecosystem. Imho this will do just fine in the meantime.