Drf-yasg: OpenAPI 3 support

[axnsan12]

The latest version of the OpenAPI specification has some interesting new features and could be worth implementing. A great overview of new stuff can be found here: https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/

It would enable support for some features we cannot currently represent:

• write_only and allow_null serializer fields via new Schema properties
• hostname versioning via server variables
• support for file types via Encoding objects
• support for more complex multipart/form parameters with the new Parameter styles and the new RequestBody object

There are also improvements like support for anyOf and oneOf, more complete security schemes, operation links and other goodies.

On the other hand, there are some considerations:

1. it is significantly more complex than OpenAPI 2.0
2. it would require non-trivial changes to both public interfaces and internal code
3. supporting both 2.0 and 3.0 at the same time is a bit complicated, so 2.0 would probably have to be dropped
4. many tools do not yet support 3.0 - the spec itself was just released in September 2017

So, as of now, this is mostly a statement of intent and personal observations - I do not have any plans of starting work on this in the foreseeable future, and certainly not until the tooling situation improves.

[luzfcb]

Someone is working on it on any fork?

[axnsan12]

Not as far as I know. There is a WIP branch, but not much progress on it.

[luzfcb]

@axnsan12 Thank you for pointing me to your branch.

I think it would be useful to get new contributions, inform the actual status of the OpenAPI 3 implementation ( openapi3 branch ), and define whats is missing and what are the current challenges to get a full implementation of OpenAPI3

I think, that in some future, maybe I may have enough knowledge to help. Okay, this is the first time I work with OpenAPI, I still know almost nothing

[luzfcb]

Good link that explain whats the difference between Swagger 2.0 and OpenAPI 3.0
http://archive.ph/HcMY4

[sireliah]

It would be nice to have OpenAPI 3.0 supported! Just leaving a comment here to signal that there is need for new version.

[francbartoli]

+1

[joeherm]

+1

[akaone]

Any updates ?

[louwers]

Can you give some pointers how one would go about implementing support for anyOf, oneOf, etc.?

2 commits on the WIP branch :sweat_smile:

[bharling]

This would be an amazing feature to have - currently struggling with documenting an api that would make great use of the oneOf feature as it could render foreignkeys or nested objects depending on query strings ( DRF FlexFields )

[Safrone]

Can you give some pointers how one would go about implementing support for anyOf, oneOf, etc.?

Redoc might be a good place to look since they have implemented at least some of those features https://redocly.github.io/redoc/

[pcraston]

👍 for OpenAPI3 support being an amazing feature to have.

Would be be great to be able to set bearerFormat: JWT (ref) so that it automatically adds the Bearer prefix .

[capehart]

We apparently have the same need as @pcraston. We'd like to support JWT auth, but will need it reflected in our docs/schema. I'm curious to know if this is still on the roadmap, as I see this issue still in someday/maybe and the WIP branch appears pretty dormant?

[KimSoungRyoul]

@axnsan12
Hi

I 'm willing to participate in these feature
i need securitySchemes or links in OAS 3.0 Spec
would you mind if tell me these feature deprecated or Not?
what is your release plan to support OAS 3.0?

[tfranzel]

Hi all! I don't want to hijack this issue, but i would like to inform you guys of our DRF OpenAPI 3.0 schema generator: https://github.com/tfranzel/drf-spectacular A few of the mentioned feature like jwt (@capehart, @pcraston, @KimSoungRyoul) and oneOf (@louwers, @Safrone) we already support.

thank you @axnsan12 for this awesome library. It did help us a lot, but like most others here we needed OpenAPI 3 and some its features. Initially, we planned to upstream our changes into DRF as they are now also developing a OpenAPI 3.0 generator, but they wanted to take it in a different (less flexible) direction. We took a great deal of inspiration from drf-yasg. So now it's an independent app. Several people use it in production already, including ourselves. Give it a try, cheers!

[d3cline]

Need to be able to set bearer, in particular in DRF the default token auth looks like this,

Authorization: Token 2a17b0081fce64aac719a32132f4f7cd4a5104f1

note the word 'Token' this is missing/non configurable. Bummer man.

[merwok]

It is configurable via subclassing, see this example: https://github.com/caravancoop/rest-framework-auth-toolkit/blob/develop/demo/demo/accounts/authentication.py#L7

DRF’s default Token model and authentication classes are basic examples, I think it’s common to replace them to add needed functionality (such as current sessions dashboard, expiration, etc)

[esseti]

Any update on supporting OpenAPI3?

[axnsan12]

I don't plan on personally implementing support, it would require changing the project structure substantially in order to allow customizations applicable to the openapi 3 schema structure. This would mean new APIs, breaking changes, and would basically amount to writing a new library.

I'd personally recommend focusing on drf-spectacular if OpenAPI 3 is important to you. I've also added a README note mentioning this.