Support OAS 3.1 ?

[chrisdudley]

Does swagger-parser support and validate OAS 3.1 files?

http://spec.openapis.org/oas/v3.1.0

[webron]

@chrisdudley not yet. It's in the plans, but there's no ETA yet.

[spacether]

Can adding type null be one of the first features?

[hurjmc]

Will the same parser jar support both OAS3.0.x and OAS3.1.x documents?

[ech0s7r]

@chrisdudley not yet. It's in the plans, but there's no ETA yet.

Hi @webron, Do you have any update about when OpenAPI 3.1.0 will be supported or the work will kickoff?

Thanks!

[amelnikoff]

Probably it's time to repeat question two months later:

Do you have any update about when OpenAPI 3.1.0 will be supported or the work will kickoff?

Thanks!

[darkbasic]

https://github.com/swagger-api/swagger-parser/commits/oas3.1

[Mark-H]

@frantuma Is there any way to help? I'm happy to throw you a €50 bounty if that helps.

[frantuma]

Hey @Mark-H, many thanks for your kind offer!

We have 3.1 in our short term roadmap, we'll add an explanation in a few days about what we're doing and how we are adding OAS 3.1 support to swagger-core and swagger-parser, sharing some design decisions, motivations, tasks involved, needed work and ongoing implementation. I'll link that in this and other tickets related to OAS 3.1 support, any thought/comment/discussion/coding and generally any help are highly welcome. Stay tuned and thanks

[spacether]

Any chance that this bug could be fixed as part of the 3.1 roadmap? https://github.com/swagger-api/swagger-parser/issues/1603 Schema types are important and when the parser processes these AnyType schemas it incorrectly sets their types as type object and array. This makes type checking not work for these use cases.

[frantuma]

As mentioned above we have 3.1 in our short term roadmap, that we are sharing here, along with some design decisions taken to reach a good balance in terms of feature set, effort and compatibility.

OAS 3.1 support in Java Swagger Core and Swagger Parser - Roadmap

OpenAPI 3.1 has been released in February 2021 and interest/requests to add support to Core and/or Parser has been growing in the past months.

We are sharing here our roadmap to add such support, along with some design decisions taken to reach a good balance in terms of feature set, effort and compatibility.

We would ask the community to provide any feedback about the chosen direction, and as always any contribution is more than welcome.

Swagger Core (branch oas3.1)

• update swagger-models to include representation of OpenAPI 3.1 fields along OAS 3.0, not including Json Schema
• update serializers, deserializers and mixin for OAS 3.1 to correctly (de)serialize new OAS 3.1 fields
• (de)Serialization of OAS 3.1 Reference Objects siblings summary and description
• update swagger-models Schema classes to include representation of OpenAPI 3.1 fields along OAS 3.0
• update serializers, deserializers and mixin for OAS 3.1 to correctly (de)serialize new OAS 3.1 Json Schema fields
• (De) Serialization of OAS 3.1 Json Schema $ref siblings

Swagger Parser (branch oas3.1)

• update OpenAPIDeserializer to correctly deserialize and validate new OAS 3.1 fields (non Json Schema)
• Deserialization of OAS 3.1 Reference Objects siblings summary and description
• update OpenAPIDeserializer to correctly deserialize and validate new OAS 3.1 JSON Schema fields
• Deserialization of OAS 3.1 Json Schema $ref siblings
• Include "Referencing" field summary and description when dereferencing/resolving OAS 3.1 refs
• update OAS 3.1 ref resolution to support JSON Schema 2020/12 de-referencing rules
• Include "Referencing" JSON Schema fields (shallow merge) when dereferencing/resolving OAS 3.1 refs

Can I help?

Sure you can, as always any contribution is more than welcome, be it feedback, PRs, reviews, etc.

Please do reach out!

Tasks summary and ongoing efforts

We are actively proceeding with implementation in feature branches for both Swagger Core and Swagger Parser, with efforts to get to a first 3.1 supporting release. Having started in September, we'll post updates as progress is made.

Affected projects

Swagger Core and Swagger Parser will be the first 2 projects implementing OAS 3.1 support (and JSON Schema 2020/12), as they provide the core features; in the medium term we'll also provide 3.1 support in Swagger Inflector, Swagger Petstore and Swagger Codegen.

in Swagger Core, the first focus is going to be in implementing support in swagger-models and swagger-core modules. This includes representation/schema + serialization/deserialization, but doesn't e.g. include updated annotations and their interpretation in JAX-RS Reader and/or ModelResolver. The plan is to introduce them iteratively along with their processing after the core modules have been implemented.

Initially therefore OAS 3.1 / JSON Schema 2020/12 will be "supported" as outcome of swagger-jaxrs2 / ModelResolver in code-first scenarios by providing a tiny converter layer translating generated OAS 3.0 spec into 3.1 (which is for the major part backward compatible with 3.1, and conflicts can be quite easily handled by converter).

In Swagger Parser, deserialization and validation will be updated to be able to support 3.1 constructs, while "resolving" (de-referencing + bundling) will be updated to handle different Base URI identification for JSON Schema along with introducing merge mechanism for $ref siblings in JSON Schema and OAS 3.1 Reference Objects.

Versioning and artifacts.

We have decided to implement OAS 3.1 support in the same code line currently providing OAS 3.0 support, i.e. master branches for Swagger Core and Parser, producing the following artifacts:

• io.swagger.core.v3:swagger-core:2.2.x
• io.swagger.parser.v3:swagger-parser:2.1.x

The alternative would have been implementing a separated code base with own set of artifacts, e.g. io.swagger.core.v31:swagger-core. There are PROs and CONs for both alternatives, the main reasons we opted for an update of existing artifacts are compatibility and maintenance effort. This comes with a price though: code branches and updates are introduced to handle both versions, introducing complexity and a less clean code. We considered however that this is a price worth to pay given the other advantages of this approach.

A separate codebase comes with a high price in terms of maintenance effort, implementing both versions support within the same code line solves this issue.

Even if semantic versioning has been dropped, 3.1 is still a minor version update, where the majority of 3.0 constructs are compatible with 3.1. Users will be facilitated by being able to keep using the same code to process both versions.

In the medium/long run, our plans include a major rewrite of both Swagger Core and Parser to improve versions handling and other areas.

Related community tickets

• https://github.com/swagger-api/swagger-core/issues/3913
• https://github.com/swagger-api/swagger-core/issues/3900
• https://github.com/swagger-api/swagger-core/issues/4013
• https://github.com/swagger-api/swagger-core/issues/3419
• https://github.com/swagger-api/swagger-parser/issues/1535

[gunsluo]

any updates on OAS3.1?

[frantuma]

@gunsluo on its way, should be very short term for parser support including dereferencing. Swagger Core support for representation/serialization/deserialization has been implemented, along with OAS 3.0 conversion into 3.1 as a (temporary) way to get a OAS 3.1 spec out of code first resolving by Swagger Core. No ETA but quite short term also (some 3-4 weeks) we are going for OAS 3.1 full support in Swagger Core code first resolving in terms of annotations and related logic

[frantuma]

#1730 implements OAS 3.1 Support in terms of parsing/validation and de-referencing / resolving.

Updated documentation about usage, features, limitations and remaining tasks will follow shortly (Swagger Core and Swagger Parser)

[spacether]

@frantuma should this be closed?

[samgqroberts]

It looks like as of v2.1.0 this can be closed https://github.com/swagger-api/swagger-parser/releases/tag/v2.1.0

[LasneF]

i agree with @samgqroberts
@frantuma , @char0n , @ponelat can you close this ticket for a cleanning reason (and also for project relying on this ticket to have a clearer status )

thx