This is probably a mixed effort between the main repo and documentation repo, but I think it fits best here.

See this thread for reference: rucio/rucio#7796 (comment)

Basically, some API docstrings might want to use enums to specify the valid values for a parameter. However, OpenAPI does not render enums well at this point:

There might be some option to decide how to render enums on the frontend side.

Also worth noting that we're planning to migrate to FastAPI, but it shouldn't affect this, since we'll still be using OpenAPI to generate the docs.