Swagger support for OpenAPI 3.0 and OpenAPI 3.1

Following the recent launch of a brand-new version of Swagger Editor, we’re happy to announce that it includes broad support for editing and rendering experiences in OpenAPI 3.0.   

It’s been a busy time across the Swagger ecosystem working towards OpenAPI 3.1 support. OpenAPI 3.1 is the latest version of the OpenAPI Specification.  

We’re now at the point where the new editor supports a rich editing experience covering features such as language specific documentation, better auto-completion, validation, syntax highlighting, “go to” reference, and “find symbols” across OpenAPI 3.0 and 3.1. Rendering for OpenAPI 3.1 will soon follow as part of the Swagger UI enhancements.  

The latest feature release accompanies the out-of-the-box support that the new editor has for AsyncAPI (versions 2.*), giving rich editing experience across both OpenAPI and AsyncAPI within your web browser.  

In addition, here’s a quick update on OpenAPI Specification (OAS) 3.1 support across the broader Swagger OSS suite of projects. 

The Swagger Core 2.2.0 release has introduced support for OpenAPI 3.1 / JSON Schema 2020/12 in terms of representation, (de)serialization, and partial support of annotations and code-first spec resolution. OAS 3.1 support has been added in the same code line currently providing OAS 3.0 support.  

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  

As of writing, support for code-first OAS 3.1 specification resolution and annotations is an ongoing effort, with 3.1 currently provided via conversion from generated 3.0. From a representation perspective, swagger-models provides a POJO representation of a OpenAPI 3.x definition.  

Swagger Parser parses (naturally) an OpenAPI specification into an OpenAPI instance provided by swagger-models module of Swagger Core. Since version 2.1.0, it supports parsing and validating OpenAPI 3.1 specifications with the same APIs used for OAS 3.0.  

It detects the version by checking the value of the OpenAPI field:  

    SwaggerParseResult result = new 
    OpenAPIParser().readLocation("./path/to/openapi31.yaml", null, null);  
    OpenAPI = result.getOpenAPI();
    

The returned OpenAPI instance will be analogous to the one obtained by Swagger Core deserialization.  

Since Swagger Parser version 2.1.0, validation also supports OAS 3.1 specification rules, which are applied when a version 3.1 definition is detected by via the OpenAPI field. Any validation errors are provided as for 3.0 within SwaggerParseResult.  

When processing an OpenAPI 3.1 specification, Swagger Parser uses a different logic to resolve (options.setResolve(true)) than the one used for 3.0 documents. Such logic is meant to be more consistent and maintainable.  

For full details of Swagger Core and Swagger Parser OpenAPI 3.1 support, check out the GitHub wiki.  

Rendering for OpenAPI 3.1 will soon follow as part of our Swagger UI enhancements. In a nutshell, the ability to process and render OpenAPI 3.1 definitions/documents within Swagger UI will be enabled by the integration of ApiDOM with Swagger Client.  

We’re expecting to have this completed in Q1 2023 which will bring the rendering capability also into our Swagger Editor tool.  

OpenAPI 3.0 and 3.1 Support Overview  

Below is an overview of the current level of support for OAS 3.0 and 3.1. We’ll follow up soon with a more detailed breakdown to the field level.  

Next Steps  

We’re committed to supporting the API community across the spectrum of API specifications and languages.  

In doing so, we’ll be opening the Swagger roadmap and providing updates on some of the latest innovations. Additionally, we want to be transparent on our specification support across our projects, so will surface that reference information shortly.  

We'd love you to get involved with our open source initiatives across Swagger. Feel free to check out our contributing guide.