OpenAPI 3.1 Support

API Hub for Design 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

API Hub for Design 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 API Hub for Design, it automatically determines the OpenAPI version of the imported API.

Programmatically

You can also create and update APIs programmatically, for example, using API Hub for Design 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 APIs 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

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