search

tfranzel / drf-spectacular

Sane and flexible OpenAPI 3 schema generation for Django REST framework.
https://drf-spectacular.readthedocs.io
BSD 3-Clause "New" or "Revised" License
2.21k stars 248 forks source link

Open API schema for django rest framework JSON:API #870

Open auvipy opened 1 year ago

auvipy commented 1 year ago

this was in drf-yasg,, so would be great if this package also provide a 3.0/3.1 compatible schema for JSON:API

tfranzel commented 1 year ago

Hi @auvipy,

I'm not entirely sure that you are referring to exactly. Correct me if I'm wrong, but drf-yasg did only OpenAPI 2.0 out of the box. As far as I can tell, this library (https://github.com/glowka/drf-yasg-json-api) provides that functionality on top of drf-yasg.

With regards to JSON:API and DRF, https://github.com/django-json-api/django-rest-framework-json-api seems to be orthogonal to drf-spectacular. Looks like we merely share the AutoSchema base classes. I have that dependency on my radar with respect to the refactoring discussed in encode/django-rest-framework/discussions/8453 though.

It seems that drf-yasg+drf-yasg-json-api is a "competitor" to django-rest-framework-json-api. Could you elaborate on what would need to be changed here? I must that admit that I am a bit confused how this all plays together.

As to OpenAPI 3.1, we are tracking that in #825 and #378, but that seems to be only indirectly related to your question.

auvipy commented 1 year ago

https://github.com/django-json-api/django-rest-framework-json-api/discussions/1082#discussioncomment-3941182 was what I was referring to. but if it is not possible I will try to make one

tfranzel commented 1 year ago

Ah thanks, that was the context I needed. I was not aware of that discussion.

So as far as I understand

drf-yasg+drf-yasg-json-api is a "competitor" to django-rest-framework-json-api

still seems to hold true. drf-yasg-json-api took drf-yasg as basis for implementation, while django-rest-framework-json-api uses DRF's native and now deprecated OpenAPI 3 AutoSchema as basis. So far so good.

I see 2 options here for django-rest-framework-json-api:

  1. The DRF AutoSchema interface is not going away! The DRF AutoSchema implementation is deprecated because it is lacking so much. django-rest-framework-json-api could absorb that implementation and patch it just as we did with drf-spectacular. This would also mean that they are free to change things and finally get their proposed PRs, that were deserted and never accepted into DRF.

  2. django-rest-framework-json-api will base their implementation on drf-spectacular.openapi.AutoSchema instead of rest_framwork.schemas.openapi.AutoSchema. Spectacular'sAutoSchema is merely an extended and super-charged derivation of DRF's version. If they can make it work with DRF's version, I see no substantial reason why this wouldn't also work with spectacular's version that just has more functionality.

I'm certainly willing to support and accommodate changes that make option 2 possible, as long as this doesn't not lead to drf-spectacular requiring a fundamental refactoring.

auvipy commented 1 year ago

I'm certainly willing to support and accommodate changes that make option 2 possible, as long as this doesn't not lead to drf-spectacular requiring a fundamental refactoring.

I think that would be more sensible approach. will communicate that with them

tfranzel commented 1 year ago

sure thing. I subscribed to that discussion. You can mention me in your communication so I can chime in where needed.

I would hate for them to walk through the valley of tears like I did. I'm certain they can benefit from a heap of already solved issues that are already baked into spectacular.