OpenAPI 3.1

[silverwind]

While the spec is not final yet, i'd be nice to have some support eventually. It eliminates some inconsistencies between OpenAPI and JSON Schema.

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md https://apisyouwonthate.com/blog/openapi-v3-1-and-json-schema

[n2ygk]

This appears to be the list of what will be in 3.1.0: https://github.com/OAI/OpenAPI-Specification/issues/2025

[lephuongbg]

3.1 RC has been released. It would be nice if Swagger UI could support it when the final version is out.

[daleione]

OAS 3.1.0 Released!

[millii19]

Is this being worked on actively? If so, is there an estimated release date?

[UkonnRa]

Any update?

[jziggas]

Just encountered a blocker with this trying to add request bodies to an HTTP DELETE method while upgrading docs. I had thought this was supported but didn't realize there is a sort of mismatch between OpenAPI versions and what SwaggerUI actually supports!

[gwerbin]

Does this depend on adding 3.1 support to Swagger Parser? https://github.com/swagger-api/swagger-parser/issues/1535

It looks like a lot of downstream projects are depending on 3.1 support from one or both of Swagger Parser and Swagger UI. Maybe it'd be a good idea to engage with some of them?

[saibotsivad]

I'm willing to put in some effort over the next several weeks to help get the Swagger UI working with 3.1, but I'm not sure how to assist with that.

I don't see any other open issues or pull requests about 3.1, and it looks like there's a major effort with the 4.x release so maybe that work needs to settle first?

[char0n]

Hi guys,

As mentioned in https://swagger.io/blog/api-design/what%E2%80%99s-ahead-for-swaggerui-v4-and-swaggereditor-v4/, 4.x release is the first step of OAS 3.1 adoption.

[johanneswuerbach]

Now that v4 has been released, is there any other tracking issue or any support needed?

[mvasin]

This post mentions that v4 will prepare Swagger UI for OpenAPI 3.1 adoption. The current Swagger UI release is 4.1.3, so we should be well-prepared for OpenAPI 3.1. 🙂 Is there actual support on the horizon?

[soyuka]

It's been almost 9 months and there's no breaking changes in OAS 3.1.x, what does it take to support it?

https://github.com/swagger-api/swagger-ui/blob/cc408812fc927e265da158bf68239530740ab4cc/src/core/plugins/oas3/helpers.jsx#L9-L13

[lephuongbg]

It's been almost 9 months and there's no breaking changes in OAS 3.1.x

There are breaking changes in OAS 3.1, specifically the JSON schema alignment where OAS 3.1 is now fully compatible with JSON Schema.

Just some examples:

• nullable is removed, in favor of JSON Schema null type
• exclusiveMaximum and exclusiveMinimum now won't accept boolean values
• Read all the release notes of alpha, beta, RC versions for more

It will take time to update Swagger to align with OAS 3.1's new behavior. Though a year is quite a long time to wait.

[karenetheridge]

IME, most of the changes from 3.0.3 -> 3.1 are pretty small, with the exception of the treatment of json schemas. Now, it is necessary to find a fully-compliant JSON Schema draft2020-12 implementation -- and it must be fully-compliant, because there are have been some tricky features added in recent versions and OpenAPI makes use of all of them (notably the unevaluated keywords, annotation collection, and $dynamicRef).

I don't know what implementations might be compatible with the Swagger software, but that's where I'd start the investigation.

[henaff]

There are a lot of ref features really useful in 3.1.0 and we are still blocked with many tools to 3.0.x We are in 2022 please

[apkrieg]

Here in 2022 as well. Waiting not only on Swagger for this, but also Postman. Both have issues for 3.1 that are well over a year old.

[M-Reimer]

The main "problem", at least for me, is that some of the tools that are affected by this Issue are actually really really cool stuff. Like "Swagger UI". This thing really helps so much with API development, documentation and testing.

If this helps someone: Until the new features are properly supported, you can just prefix them with "x-" to get valid OpenAPI 3.0 syntax. I did that for "unevaluatedProperties" as I needed this for our API design.

[antoniogamizbadger]

Any update on this? or estimation?

[soyuka]

There are breaking changes in OAS 3.1, specifically the JSON schema alignment where OAS 3.1 is now fully compatible with JSON Schema.

I have to disagree as I was speaking about the Open API specification, not the JSON schema ones (I read the release notes). Also, I don't see where the JSON schema is impacting in the Swagger UI. Just allowing an Open API specification to render with the swagger UI will allow people to at least use it.

I really think that we should consider at least https://github.com/swagger-api/swagger-ui/pull/7719 which allows 3.x versions to be showed by the Swagger UI.

[gwerbin]

@soyuka the OpenAPI 3.1 specification mandates that schema documents themselves conform to JSON Schema Draft 2020-12. So a JSON Schema validator that supports the 2020-12 draft is essential for supporting OAS 3.1.

Moreover, it adds a jsonSchemaDialect option, which allows you to specify your schema objects in the JSON Schema dialect that you choose, which (from my reading of the spec) could be any valid JSON Schema version.

It is true that, in practice, mostly the incompatibility comes down to nullable: true vs. type: ['null', ...], but tooling like Swagger UI probably should support the full spec, not an ad-hoc subset.

[Hypfer]

There's nothing mandating that you have to install this official package of swagger-ui. If the hack proposed in #7719 works for your use-case, then why not just fork the repo and use that until mainline gains proper support?

[soyuka]

I don't really use swagger-ui but we bundle it inside API Platform and I'm trying to find a solution for everyone :). What can I do to help mainline gain proper support then? I can fix the nullable feature. About the JSON schema I don't really know how Swagger-UI uses that but I can take a look.

So a JSON Schema validator that supports the 2020-12 draft is essential for supporting OAS 3.1.

Where are you using a JSON Schema validator? I checked swagger-api/swagger-js it doesn't seem to use one. Are you building one or are you trying to update one that's already available?

Moreover, it adds a jsonSchemaDialect option, which allows you to specify your schema objects in the JSON Schema dialect that you choose, which (from my reading of the spec) could be any valid JSON Schema version.

This is a new feature that isn't supported yet, do we really want to support this as more and more people want to upgrade to 3.1.x?

On a general note, please don't see anything negative on my answers, I'm just trying to push things forward and have time to help. Maybe that starting a Github project with a few tasks would help us organize things to move forward?

Thanks for your time.

[philsturgeon]

Just a heads up here for anyone looking for something like Swagger UI that supports OpenAPI v3.1, there are quite a few options out there: https://openapi.tools/#documentation

• Bump
• Elements
• OpenAPI Explorer

As always check out https://openapi.tools/ for more tooling, it will says which versions they support right on the page.

[a-akimov]

I just wanted to draw attention once again to this issue. OAS 3.1.0 was released more than a year ago and this was such a fundamental step because of the compatibility with JSON Schema. Postman now supports 3.1.0 too; a lot of other tools as well. However, Swagger UI still doesn't but this is so crucial for the entire API industry to move forward with adopting OpenAPI 3.1.0.

Please consider prioritizing this issue or at least sharing some timelines regarding it.

[Hypfer]

@a-akimov do you happen to have support contract with SmartBear Software?

[a-akimov]

@a-akimov do you happen to have support contract with SmartBear Software?

No. If you think there exist any options that could help with this case, please let me know and I will explore more.

[peterrexer-sureify]

Do you have a timeline? An estimate on when you'll have a timeline? A guess on when you'll have an estimate on having a timeline? A comment?

My team is going to move to Stoplight in the next few weeks as we have features that use 3.1 that we're publishing APIs for very very very soon.

[philsturgeon]

Hello! As the maintainer of openapi.tools, and as somebody works with Linux Foundation helping out in OpenAPI-land, I'm reaching out to tooling vendors to track the progress towards supporting OpenAPI v3.1, to see what roadblocks there are beyond folks just generally being busy at this ridiculous time.

OpenAPI v3.1 has a bunch of great little changes, solving problems like the JSON Schema <!=> OpenAPI Schema Object divergence. It also fixes some other inconsistencies and duplicate ways of doing things. It's the best version and everyone should be using it, but we need tooling to catch up. Just in case folks didn't notice, or don't have resources to simplify the process, I'm here to give a friendly prod and send over some handy links.

Here are a few articles showing off the differences between OpenAPI v3.0 and v3.1.

• https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
• https://www.apimatic.io/blog/2021/09/migrating-to-and-from-openapi-3-1/
• https://nordicapis.com/whats-new-in-openapi-3-1-0/

Here are some example files which can make for handy pass/fail test cases:

https://github.com/Mermade/openapi3-examples/tree/master/3.1

If you're looking for the JSON Schema that defines a valid OpenAPI document, that'll be right over here:

https://github.com/OAI/OpenAPI-Specification/tree/main/schemas/v3.1

No rush, but when you're starting work on it, please update this issue so I can update openapi.tools to reflect that, and folks will have a way to subscribe for updates.

LMK if you have any questions!

[ponelat]

Thanks for the ping @philsturgeon :) And thanks for everyone's patience on this thread.

So what's happening with Swagger UI and OpenAPI 3.1? Here is the tl;dr version, as we figure out how to better engage and communicate around roadmap items.

• We're working on a new Swagger Editor first, which is built on a new parser/engine.
• The engine/parser thing will be where we address resolving and validating OAS 3.1 definitions.
• After that we'll have a foundation for Swagger UI to render OAS 3.1 definitions.

Will update this thread when we have more messaging around that. Happy Friday! :tada:

[mrlubos]

Very much looking forward to it @ponelat!