What’s New in SwaggerHub: OpenAPI Specification 3.1

Hot on the tail of Swagger’s OpenAPI 3.1 support announcement, I am pleased to share that we’ve launched our initial support for OpenAPI 3.1.

TL;DR – in SwaggerHub, now you can:

• Catalog OpenAPI 3.1 APIs using SwaggerHub as single source of truth.
• Design OpenAPI 3.1 APIs with the new, more powerful Swagger Editor.
• Retain the documentation for all your APIs, including those using OpenAPI 3.1 and AsyncAPIs.
• Leverage new features of OpenAPI 3.1, such as support for JSON Schema 2012-12.

This release is just the beginning for SwaggerHub, and we’re committed to bringing you complete support for OpenAPI 3.1 soon. Below details the points above, plus our plans for feature parity with OpenAPI 3.1, for a complete API development and management workflow.

Building Support for OpenAPI 3.1 in SwaggerHub

While adding a mere “dot-one” may seem like a minor release, it comes with a major unbundling of the way we can now describe models and schemas – the shape of the JSON, XML, and Form bodies that flow through the API in requests and responses.

OpenAPI 3.1 has support for the full breadth of JSON Schema (specifically the latest at time of writing, which is JSON Schema Draft 2020-12) and conceivably any version of JSON Schema (although, as tool makers we have limited this somewhat in Swagger. See below for what isn't supported).

What Does This Mean?

Historically, OpenAPI has supported a subset of JSON Schema and has even had different semantics for the same keywords. This has meant that reusing schemas required transforming them between the “OpenAPI-flavored JSON Schema” and other versions of JSON Schema proper, reducing the ability to describe a source of truth for a schema and limiting reuse.

OpenAPI also has been conservative in what features of JSON Schema its supports. This has been good for tool makers, who were able to fully support OpenAPI, but also has left features on the table – features that allow for more power in describing real-world APIs.

Now that OpenAPI has surrendered to fully supporting JSON Schema, we can expect two things:

1. A slow ramp up of tools to get to feature parity, given how powerful and sophisticated JSON Schema can be.
2. An explosion of reusability between OpenAPI, AsyncAPI, JSON Schema tooling, and potentially other specifications.

Where Are Swagger and SwaggerHub in This?

In the open source, the various Swagger projects have been incrementally and sometimes completely rewriting themselves to support OpenAPI 3.1, from the core Java and JavaScript libraries, through to the user-facing tooling such as Swagger Editor and Swagger UI. With one notable exception, work continues on Swagger Codegen. Read more: Swagger Supports OAS 3.1.

Cataloging RESTful APIs in OAS 3.1 with SwaggerHub

SwaggerHub is proud to now also boast full support for OpenAPI 3.1 in its cataloging features.

Up until now, where teams have already started creating APIs with OAS 3.1, they have not been able to store them in SwaggerHub – but today this changes. You can create, or import, OAS 3.1 APIs into SwaggerHub to have a single source of truth for all your API portfolio management.

Three examples of this are:

• Create, search, and filter your OpenAPI 3.1 definitions.
• Design OpenAPI 3.1 definition with the new, more powerful Swagger Editor.
• Standardize OpenAPI 3.1 with custom linting rules.
• And of course, view and try out documenting with interactive documentation.

The benefit of using SwaggerHub is centralizing the cataloging of these different APIs, supporting collaborative workflows, and reducing costs through standardization and governance. Keeping both RESTful and event-driven APIs close together is an important step in managing a portfolio.

With this single API catalog, developers, architects, designers, and consumers alike can benefit from improved discovery and heightened governance.

Designing RESTful APIs in OAS 3.1 with SwaggerHub

The launch of the new Swagger Editor in late 2022 was a milestone to get us to where we are now, supporting the design of RESTful APIs with OpenAPI 3.1. A substantial advancement with the new Editor is the ability to support multiple API specifications while also ensuring ease of extension.

Now you can create, document, and test RESTful APIs in OAS 3.1 while you maintain current best practices and standards.

Documenting RESTful APIs in OAS 3.1 with SwaggerHub

Keep accurate, up-to-date documentation for APIs written with the OAS 3.1 specification in SwaggerHub. Generate interactive documentation automatically during design, so both API consumers and internal users can learn about and work with your APIs.

Import or host OAS 3.1 APIs and AsyncAPI definitions in one central platform and manage versioning and publishing of the documentation to ensure consistency.

What’s next?

This initial release is our starting point. We are committed to extending OAS 3.1 support across SwaggerHub. Up next, we will build further critical features needed to effectively manage your API’s lifecycle, such as furthering collaboration and integrations.