Support OAS 3.1

[black-snow]

Is your feature request related to a problem? Please describe.
OAS 3.1 hasn't settled yet but is quite close to being final (afaik). I couldn't find any issue / roadmap tracking progress for this - please close the issue & hint me if I'm blind.

Describe the solution you'd like
Support OAS 3.1 RC0 / JSON-Schema 2019-09 and keep on improving until it's final.

[nijikokun]

Good call-out @black-snow still waiting for the third-party libraries to catch up 👀

[black-snow]

not stale

Haven't check for a while, has anything happened here in the meantime @nijikokun ? https://spec.openapis.org/oas/v3.1.0 is out.

[black-snow]

Am I the only one working with 3.1+? :D

[Stokestack]

No. I just tried to open my OpenAPI file and Insomnia complained because it specifies version 3.1.

[dimitropoulos]

Could you give a specific example, please, of something you need from OAS 3.1? It will help get the ball rolling.

[black-snow]

sadly, it's now been a while since I had to doc an API so I can't be super specific - I remember coming from JSON Schema, example vs. examples was a small issue -- I don't fully remember, it's been almost a year :/

[tfedor]

@dimitropoulos e.g. array type, multiple examples or updated JSON Schema support to 2020-12? Pretty please

[Stokestack]

This is a real issue. I don't remember all of what's added in 3.1, but it's very important to be able to put descriptions alongside the use of references. I can't imagine why this was ever prohibited.

For example, if you've defined a schema called Rectangle and you want to use it by reference in various places in your API, pre-3.1 OpenAPI wouldn't let you describe what you were using it for in each instance. Baffling.

[dimitropoulos]

for what it's worth: our upstream already merged support for OSA 3.1 APIDevTools/swagger-parser#191 but they're having trouble making an npm release: APIDevTools/swagger-parser#191

[black-snow]

for now

[miketheman]

Looks like they resolved the release issue 6 days ago 🎉

[brookmg]

Is this issue resolved?

[black-snow]

haven't checked for a while - might be able to on monday

[Wazbat]

Looking forward to this. There's a few nifty features in 3.1 I'd love to use