OpenAPI 3.1 Support

SwaggerHub supports OpenAPI 3.1 (OAS3.1), a major enhancement of OpenAPI 3.0. OpenAPI 3.1 introduced new features like:

complete JSON Schema compatibility
better webhooks descriptions
API license identification via the standard SPDX identifier
simpler creation of reusable component libraries

SwaggerHub supports OpenAPI 3.1 for API design and documentation.

OpenAPI 3.1 is an open-source community, specification, and toolset. For more information about the ecosystem, see OpenAPIs.org.

Considerations

Keep the following in mind when using OpenAPI 3.1:

Interactive API documentation is based on https://github.com/swagger-api/swagger-ui. We endeavor to keep it as up-to-date as possible but will lag behind the bleeding edge.
Currently, OpenAPI 3.1 doesn't support the following features:
- Domains
- Custom Templates
- Basic SCM Plugin Integrations
- Auto mocking
- Side Navigation panel
- Convert from 2.0 and 3.0
- Codegen

Create OpenAPI 3.1 definitions

Manually

When you create a new API, use the Specification combo box to choose OpenAPI 3.1.x.

When you import API definitions to SwaggerHub, it automatically determines the OpenAPI version of the imported API.

Programmatically

You can also create and update APIs programmatically, for example, using SwaggerHub CLI or Registry API.

curl -X POST "https://api.swaggerhub.com/apis/MyOrg/MyApi"
     -H "Authorization: YOUR_API_KEY"
     -H "Content-Type: application/yaml"
     --data-binary @./path/to/myapi.yaml

The specification will be automatically detected.

How to tell if a definition uses OpenAPI 3.1?

OpenAPI 3.1 specifications begin with openapi: 3.1.0.

You can recognize OpenAPI 3.1 definitions in the MY hub and other search results pages as they are displayed with the badge.

To search for APIs that use the OpenAPI 3.1 specification, click on the search bar and choose OpenAPI 3.1 from the Specification pulldown so that only OpenAPI 3.1 APIs will be included in the search.

Learn more about OpenAPI 3.1

To learn more about OpenAPI and Swagger tooling, see OpenAPI 3.1.

The OpenAPI 3.1 specification is available on OpenAPI 3.1 Specification pages.