Switch to drf-spectacular as OAS scheme generator

[n2ygk]

Per encode/django-rest-framework#8453 upstream DRF is deprecating the internal schema generator in lieu of recommending use of drf-spectactular so we'll need to do the same since our openapi schema support extends DRF's and there have been outstanding upstream improvements (such as encode/django-rest-framework#7516) that will never be implemented in DRF.

[sliverc]

Thanks for bringing up this discussion.

So far schema generator has not been deprecated in DRF. Once it is, we should also follow and deprecate it in DJA. Till then, I am happy to integrate small improvements like doc updates or obvious errors etc.

As OpenAPI won't be a direct feature of DRF anymore and also not a requirement of the JSON:API spec I would love to see a separate library based on drf-spectacular to be developed like drf-spectacular-json-api. This would follow the spirit of DRF and drf-yasg-json-api is a great example where this worked out well.

Would be anyone willing working on such a library?

[sliverc]

@axieum Thanks for offering your support. Just to clarify for now no-one is forced to move to OpenAPI 2.0 as OpenAPI 3.0 schema generation in DJA is still possible and we also still integrate small fixes just like the recently accepted PR #1124. Also, as far as I understand in DRF small schema generation fixes are also integrated for the time being. However, at some point it will be deprecated and removed and it will be good to get prepared for this. I assume @jokiefer hasn't had time yet to get started with drf-spectecular-json-api. However, if you are willing to get it started, I have a feeling people will follow and support you, someone simply needs to take the lead.

[jokiefer]

Hi folks!

i started the project here drf-spectecular-json-api.
First testable version is available from pypi.

It contains not all possible describable schema feature for now. but the basics are done.

Happy testing.

[sliverc]

@jokiefer Awesome. While implementing, if you encounter any issues which need a change in DJA directly, let me know. Happy to assist.

[jokiefer]

@sliverc The only thing from DJA i needed to overwrite for now was the Pagination class and there get_paginated_response_schema function. But in my pov, this function shall return an openapi schema and this shall not be a part of the DJA project.

I think IF DRF drops openapi support this function would also be deprecated.
This was also the mention you discovered in commet @tfranzel?

[tfranzel]

@jokiefer awesome stuff! Interesting to see the actual changes required. Like @sliverc said, feel free to also raise issues on my end. Happy to support you here.

Regarding your question. I don't think this function will be dropped. At the end of the day the interface will remain and you could see that as part of the interface. This is worth a discussion and the maintainers can certainly be swayed in that regard if we make a good case of it. We can come up with an alternate approach if necessary, but I don't think it will come to that.

What was mentioned in that comment was more meant towards the required changes in the documentation not the interface itself.