OpenAPI3 proposal for enhancements/fixes

[ghost]

Checklist

• I have verified that that issue exists against the master branch of Django REST framework.
• I have searched for similar issues in both open and closed tickets and cannot find a duplicate.
• This is not a usage question. (Those should be directed to the discussion group instead.)
• This cannot be dealt with as a third party library. (We prefer new functionality to be in the form of third party libraries where possible.)
• I have reduced the issue to the simplest possible case.
• I have included a failing test as a pull request. (If you are unable to do so we can still accept the issue.)

Description

We tried using DRF OpenAPI3 for our production API, but soon found that the capabilites are severely limited and it does not cover a lot of things that more complicated APIs (heavily customized views and serializers) require:

• openapi-generator breaks on direct schemas (i.e. schemas that are not put into components), which makes the generated spec unusable for client generation.
• easy & low boilerplate adaptation of schema for each usecase/endpoint
• Swagger UI should look presentable

Furthermore, some of the previously raised issues are covered in the PR for this issue, some of which are #6984 #7069 #6882 #6858 #6844 .

The existing code was a great starting point. thanks for all the hard work. We also took inspiration from the awesome OpenAPI2 library https://github.com/axnsan12/drf-yasg

A list of implemented features can be found in the PR.

[tfranzel]

To @fyhertz @Reshurum @glebovmaksim @stefanitsky @Behoston @dhaval-mehta @Lucidiot @fangaofeng @auvipy @jgadelange @carltongibson and other who might have been interested in this.

We proposed massive changes to the schema generation, but only some parts got accepted. Indeed our PR #7089 was way to big and decomposing it (while retaining the functionality) was quite challenging.

In the end one of our core mechanics (#7096) got rejected in favor of #7124. Since this did not allow for the flexibility we required, we had to go another route.

For that reason we released our approach to schema generation as standalone package drf-spectacular https://github.com/tfranzel/drf-spectacular. Since the PR we did a lot more improvements so check it if you like. Happy for any PRs, suggestions & comments.

[stefanitsky]

@tfranzel hi! Thanks, very interesting!

[dhaval-mehta]

@tfranzel, very interesting!

I have 2 concerns.

1. OpenAPI code changes frequently. Syncing with DRF will become a challenge.
2. Many people will not be aware of this package. If we all together can work to break OpenAPI3 proposal for enhancements/fixes #7089 into small chunks, Each chunk will get merged. If this happens, all users of DRF will get benefited from your hard work.

[tfranzel]

@dhaval-mehta I absolutely get your concern. That is why I created the PR in the first place. Let me comment on your concerns.

1. It has very few dependencies to the core code and its getting less. The one central requirement is the AutoSchema concept, which will most likely not go away in the near future.
2. The code progressed too far away to have a serious chance of getting merged imho. Also the fantastic drf-yasg was never shipped with DRF (which we used before).

Apart from that I believe it also has benefits shipping as a separate tool. We can iterate faster and provide support for popular 3rd party apps. Pretty sure those pieces would have a very low chance of ever getting merged (and rightfully so).

Honestly we really needed a "usable" OpenAPI3 schema rather sooner than later. The DRF code was far away from being useful to us and the drf-yasg branch for OpenAPI3 has been stale for a while now.

We literally found ourselves in the same situation as @Behoston in #7205. Initially, I was super stoked when I saw that OpenAPI3 generation was released in 3.10, but soon found out that it was more or less in a "pre-beta" state. Don't get me wrong, I love DRF and deeply appreciate all the hard volunteer work from everyone. I agree with @carltongibson that it is indeed maturing very nicely, although I would argue that it should not have been officially released in that state yet. This being DRF and all where released code is usually top-notch and not filled with a lot of #TODOs.