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.

[creyD]

Hi @JoelLefkowitz, hope you are doing good. I saw that you created 2 releases today, is this indicative of a trend? Is there any hope that we get OpenAPI 3 support with you? Or is this more or less a one time fix?

[JoelLefkowitz]

Hey @creyD thanks for mentioning. I’ve actually dedicated some time in my daily schedule to process all the outstanding tasks in this repo and undertake some new features at a more consistent rate rather than in bursts.

As it stands my priorities are:

Processing contributions:

• Existing PRs
• Closing resolved issues
• Triaging stale issues

Improving automation:

• Decluttering the top level of the repository
• Adding a distinct linting step
• Adding a dependency tool (rather than multiple requirements files)
• Reducing unit test time
• Deploying the Heroku app with each release

New features to consider:

• OpenAPI 3.x support
• More expansive documentation
• Python 3.10 and Django 4.0 support

The recent releases are documented in the changelog. 1.20.3 contained unpublished PRs that had been merged into 1.20.x and 1.21.0 was a new feature. I will be packaging groups of significant changes as they are merged.

Before I commit to OpenAPI 3.x support it is necessary to explore how drf-yasg and drf-spectacular can offer the most useful features for their users without wasted duplication. Personally I think it is the next big feature to add but it may be that a large proportion of this package’s contributors feel another feature is a higher priority. Open to suggestions from everyone.

[creyD]

@JoelLefkowitz That sounds great and thank you for doing it! Please let me know if there is anything I can help with. I built a autopep8 action a while back, which might be able to help with automating the listing step to a degree.

On the drf-yasg and dry-spectacular thing, it might be a future project to try to merge these two, as they are extremely similar in scope and the combined efforts would be beneficial for the DRF community. That being said, I know that this would be a pretty complex undertaking and is unlikely to take place.

[JoelLefkowitz]

Having looked at the differences between OpenAPI 2.0 and OpenAPI 3.0 I believe we can support both and allow users to specify which they wish to target.

[creyD]

That would be extremely good. Like I said, you may reach out if you need any help!