Swagger Supports OpenAPI 3.1

Swagger Launches Support for OpenAPI 3.1

We’re delighted to announce general support for OpenAPI 3.1 across the Swagger open-source ecosystem.

TLDR;

🎉Swagger now supports editing and rendering support for OpenAPI 3.1.

Swagger offers rendering support for JSON Schema 2020-12.

OpenAPI 3.1 support added across Swagger UI, Swagger Client, Swagger Editor (Next), Swagger Parser, Swagger Core, and ApiDOM.

Check the Swagger open-source project details on swagger-api.

Following earlier updates and new product launches, where rich editing and validation experiences where added, rendering of OpenAPI 3.1 documents is now supported within Swagger UI, as well as broad support for the latest version of the JSON Schema Specification (Draft 2020-12).

This milestone accompanies the out-of-the-box support that the new Swagger Editor has for AsyncAPI (versions 2.*), meaning that Swagger brings rich experiences for development teams working across all versions of OpenAPI and AsyncAPI.

What is OpenAPI 3.1?

OpenAPI 3.1 is the latest version (at time of writing) of the OpenAPI Specification (OAS). The Open API Specification defines a standard, language-agnostic interface description for HTTP APIs. It allows both humans and computers to understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. 

With OpenAPI 3.1, the OAS Technical Steering Committee (TSC), following community debate, made the decision to not follow semantic versioning. This allows certain breaking changes to accommodate alignment with JSON Schema 2020-12 and address learnings from OpenAPI 3.0, into a minor version bump. The changes are documented as part of the release notes. 

There are many improvements included in OpenAPI 3.1. For us, the standout additions/changes being:

• The Schema Object is now fully compliant with JSON Schema Draft 2020-12, and primitive types have been updated to be based on JSON Schema Draft 2020-12.
• `Webhooks` have been introduced as a top-level field to the OpenAPI Object allowing the description of out-of-band registered webhooks available as part of an API.
• The Components Object now allows for defining pathItems, promoting reusable Path Item Objects within an OpenAPI document.
• The Info Object supports having a summary field alongside the pre-existing description field.
• The License Object has a new identifier field for SPDX license codes.
• What constitutes a valid OpenAPI document has also changed. The specification now requires at least one of paths, components or webhooks to exist at the top level. Previous specification versions required paths. Now a valid OpenAPI Document can describe only webhooks, or even only reusable components.

For a detailed list of changes, check out this article by Mike Ralphson (OAS TSC Member). 

OpenAPI Support Across Swagger

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

What’s Next

The next focus will be on closing any of the gaps found in OpenAPI 3.1 support. Also, collaborating with the broader community to ensure bedding-in and adoption of the latest Swagger capabilities for OpenAPI 3.1.

We’re committed to supporting the API community across a broad spectrum of API specifications and languages. In doing so, we plan to open our Swagger roadmap and provide updates on some of our latest innovations. To be transparent on our specification support across projects, we’ll 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, and feel free to make a difference.