Swagger support for OpenAPI 3.0 and OpenAPI 3.1

  January 24, 2023

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. 

Swagger Core  

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  

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.  

Swagger UI and Swagger Client  

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.  

OAS   

ApiDOM  

Swagger Editor (next)  

Swagger Core  

Swagger Parser  

OpenAPI Object  

Info Object  

Contact Object  

License Object  

Server Object  

Server Variable Object  

Component Object  

Paths Object  

Path Item Object  

Operation Object  

External Documentation Object  

Parameter Object  

Request Body Object  

Media Type Object  

Encoding Object  

Responses Object  

Response Object  

Callback Object  

Example Object  

Link Object  

Header Object  

Tag Object  

Reference Object  

Schema Object  

✓ (Some limitations)  

✓ (Some limitations)  

✓ (Some limitations)  

✓ (Some limitations)  

Discriminator Object  

XML Object  

Security Scheme Object  

OAuth Flows Object  

OAuth Flow Object  

Security Requirement Object  

Specification Extensions  

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.