DjangoFilters: Add description for enum choices

[valentijnscholten]

The choices in a ChoiceFilter (enum) can be documented via the description, similar to what's already in place for OrderingFilter.

This will help users, for example in SwaggerUI.

No idea if this is the best way / place to implement this, but it works locally at least.

Before:

After:

[codecov]

Codecov Report

Merging #403 (411132e) into master (2684fda) will increase coverage by 0.03%.
The diff coverage is 100.00%.

❗ Current head 411132e differs from pull request most recent head 69d3a14. Consider uploading reports for the commit 69d3a14 to get more accurate results

@@            Coverage Diff             @@
##           master     #403      +/-   ##
==========================================
+ Coverage   98.51%   98.55%   +0.03%     
==========================================
  Files          55       55              
  Lines        5394     5388       -6     
==========================================
- Hits         5314     5310       -4     
+ Misses         80       78       -2     

Impacted Files	Coverage Δ
drf_spectacular/contrib/django_filters.py	86.27% <100.00%> (+0.56%)	⬆️
tests/test_regressions.py	100.00% <0.00%> (ø)
tests/__init__.py	98.14% <0.00%> (+3.70%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2684fda...69d3a14. Read the comment docs.

[tfranzel]

hi @valentijnscholten, that is a very nice idea and it has come up before in #337

as a matter of fact i do like this from a UI perspective, but i would prefer to have a structured approach via OpenAPI. others have raised this pain point in OAI/OpenAPI-Specification#681. maybe we should show some support there.

unfortunately it looks like it didn't make into 3.1.

[valentijnscholten]

OK, didn't see that. I got this info from the official swagger docs, so I was expecting it to be common. Since it's just a few lines of code, I feel it wouldn't hurt to have this merged until (maybe in the distant future) there's a more structured solution from OA.

[tfranzel]

it is true that this would would most likely not break anybody.

we are still waiting for adoption of 3.1 in upstream projects like swagger-ui. i suppose 3.1.1 or 3.2 support is not gonna be available in the near future. with that said it's probably reasonable to support this in the meantime. it's just tricky to take features out again when the time comes, but the benefits probably outweigh the risk.

if we gonna move forward here, we would also need this for the non django-filter case. maybe factor out the the string generation into plumbing.py so we can use it in the other places too.

[tfranzel]

• the > looks weird.
• we should add an empty line as separation if there is an description
• i don't like the way the empty backticks look

[valentijnscholten]

I thought the '>' and backticks where part of the official format needed, but it looks like they can be removed/changed, committed that. I did add the '\n' but it doesn't seem to do anything for the json spec, not even sure if json supports multiline strings".

My first attempt was by modifying the build_choice_field in plumbing.py, but these fields from DjangoFilters don't seem to pass through there. Or do you suggest to add code there as well as keeping it in the django filter part?

[valentijnscholten]

I have extracted the description generator code and added a call in publing.py#build_choice_field. This seems to work for some fields, but not for all:

• A BaseCSVFilter based filter: still works OK as before: OK
• A ManyToManyRelatedField based filter: gets the description generated twice: NOK
• A model CharField with choides: response schema does not get the description: NOK

I am happy to help out further, but don't really have the time to fully dive into all the schema generation code in here. Do you maybe have some pointers of where this description would be best construct to fix these NOK cases @tfranzel ?

[tfranzel]

hi @valentijnscholten, looks nice! please squash together the commits and force push for a clean history. i'll take over from there. can't really give pointers here. i would have to investigate myself on how to resolve the remaining issues.

i'm pretty strapped for time at the moment. it will take a few days for me to get to it.

[valentijnscholten]

sqaushed. thanks for looking into it, no rush, good to know it will eventually be implemented.

[tfranzel]

superseded in favor of #952.

@valentijnscholten thank you for this PR. There were a couple more things to address with this feature, namely the postprocessing hook and non-django-filter behavior. Took me a while to get around to it.

Please review this other PR whtether it adresses your points. Would be great if you could do it by end of the week, so that we can do a pending release.

[valentijnscholten]

It's been almost two years since I did anything in API spec related stuff in django, so I'm going to rely on you for this one :-)

[tfranzel]

Ahh ok, sry you won't benefit from this anymore. Have a good one.

[valentijnscholten]

Defect Dojo is still using it, so there will be benefit :-) Thanks for implementing the suggested enhancements.