Documentation request: Improve migration guide / differences cheatsheet from drf-yasg

[TauPan]

Hi!

First of all:
Thanks for your efforts. I appreciate somebody stepping in to support openapi 3 for autogenerated DRF-docs. I frequently have things I can't do with drf-yasg / swagger and I would really like to use openapi 3.

A couple of months ago (July 2020) I've experimented with porting our codebase from drf-yasg to drf-spectacular but gave up after half a day or so. At that time it wasn't clear to me:

1. Which features of drf-yasg were not supported (yet, at that time) by drf-spectacular
2. Which differences I may have missed in the documentation or code and just used the wrong approach to port them.

I think https://github.com/tfranzel/drf-spectacular/blob/master/docs/drf_yasg.rst was identical to the current version back then.

Now I'm thinking to try again, but feel somewhat reluctant, because the documentation hasn't changed and I don't know if I will hit another stumbling block.

These are my notes from back then. Possibly some of those would be appropriate as separate issues, but I want to focus on my stumbling blocks here:

• We use a mixin of AcceptHeaderVersioning and QueryParameterVersioning. The former is encouraged for production code, the latter can be used for convenience in the browsable api, and is still not supported. drf-yasg parses the version header from the query and allows us to display links in the documentation for switching between versions. (Migrating to UrlPathVersioning or NamespaceVersioning would not be feasible.)

• It seems that drf-spectacular did not pass the request at all. This looks like it's fixed by now django-filters emits warnings during schema generation #81

• Resources and Actions didn't have titles and it wasn't clear how to display them.

• Similarly, mapping docstrings to views/actions didn't happen the way it did in drf-yasg and it wasn't clear to me how. More docstrings #107 (comment) seemed related (also closed by now).

So insofar as there are fixed bugs or new implemented features it might be helpful for new users like me to upgrade drf_yasg.rst accordingly and/or clarify what is not supported by drf-spectacular yet.

If I should file a separate issue for some of these items, please tell me so.

[tfranzel]

Hey @TauPan, thanks for your kind words. much obliged.

so if you used 0.9.11 there have been 116 commits filled with a lot of improvements and bugfixes all around. i would hope a lot of your issues have disappeared, but that is hard to say for sure. i have learnt that people use DRF very differently and thus different problems may arise.

Which features of drf-yasg were not supported (yet, at that time) by drf-spectacular
Which differences I may have missed in the documentation or code and just used the wrong approach to port them.

well even though the interface for yasg and spectacular is very similar (and identical in some place), there are things that differ. also the implementation differs considerably, which means that some aspects may be better (imho) and other may possibly be worse. given the nature of these "introspection" libraries, it is very hard coming up with a meaningful and complete list of feature differences and capabilities.

regarding your points, i believe there have been quite a few improvements:

We use a mixin of AcceptHeaderVersioning and QueryParameterVersioning. .....

AcceptHeaderVersioning has been added by #144 and has since been improved a few times. path versioning should also work as expected.

It seems that drf-spectacular did not pass the request at all. This looks like it's fixed by now #81

at some point we only passed the request if the schema was served over the API, but CLI generation had no request. now we either provide the request or create a mock request, which has worked pretty well so far. (#145 and e3103ed)

Resources and Actions didn't have titles and it wasn't clear how to display them.

we currently have a PR (#191 - issue #140) for that if you refer to the title field in the schema. could you comment a bit more on your usecase and what "display" means? if i take SwaggerUI as example, the display field is not that prominent. maybe this could be addressed more thoroughly in a separate issue.

Similarly, mapping docstrings to views/actions didn't happen the way it did in drf-yasg and it wasn't clear to me how. #107 (comment) seemed related (also closed by now).

so strictly speaking the concept of views does not exist in the schema, only endpoints. what we do is trying to get the most appropriate docstring if available. so either use string from extend_schema, the view method docstring or fall back to the View class docstring. (excluding library docstrings). a cannot remember exactly what yasg was doing here. can you comment on the differences?

the documentation did only change marginally, but the migration page is the same, that is true. it was meant as a starting point and not an exhaustive guide when i wrote it. if generally applicable, would be happy for any contributions there. imho, it also not that easy to cover everyones workflow there.

with all that said, i'm happy to address issues that are still blocking you. furthermore i'm very interested in things that yasg can do and we don't. sharing your experience there would be very valueable.

[TauPan]

Ok looks like I need to re-try the migration later and take more specific notes and check if I still encounter problems.

I can't promise to do that very soon, but it looks like drf-spectacular will remain in the list of candidates (at least I don't know of any alternatives).

[tfranzel]

yeah sure. i'll close this issue for now. feel free to open new issues for any remaining problems you encounter. usually the required changes are minimal and quickly done. there aren't many fuzzy spots left.