OpenAPI 3.0 (OAS3) is the latest version of the OpenAPI Specification (formerly known as Swagger Specification). OpenAPI 3.0 introduces many new features, including multiple servers, callbacks, links, better content negotiation, new authentication types, and more.
SwaggerHub supports OpenAPI 3.0 for API design and documentation. SwaggerHub also includes a 2.0-to-3.0 converter that lets you quickly convert your existing OpenAPI 2.0 definitions without having to update them manually.
Please keep the following in mind when using OpenAPI 3.0:
Using OpenAPI 3.0 domains in SwaggerHub On-Premise requires v. 1.19.3 or later.
Available server and client code generators are limited, but new generators are added regularly.
Interactive documentation does not support:
examplesin header parameters,
using response links to initiate other operations.
automatic examples for
anyOfschemas. A workaround is to add schema examples manually:
oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' example: petType: dog name: Rex
When an API is converted to OpenAPI 3.0:
Comments are not copied to the converted definition.
Any referenced domains are not automatically converted to OpenAPI 3.0.
OpenAPI 3.0 APIs cannot be converted to OpenAPI 2.0.
Domains cannot be converted between OpenAPI 2.0 and 3.0. As a workaround, you can create a new OpenAPI 3.0 domain and update the syntax and domain references manually.
Create OpenAPI 3.0 definitions
When you create a new API or domain, use the OpenAPI Version combo box to choose the definition format – OpenAPI 3.0 or 2.0. This choice also determines the available API templates.
When you import API definitions to SwaggerHub, it automatically determines the OpenAPI version of the imported API.
SwaggerHub On-Premise note:
When uploading OpenAPI 3.0 files using Registry API, you must use the
oas=3.0.0 query parameter:
curl -X POST "http(s)://SERVER/v1/apis/MyOrg/MyApi?oas=3.0.0" -H "Authorization: YOUR_API_KEY" -H "Content-Type: application/yaml" --data-binary @./path/to/myapi.yaml
In SwaggerHub SaaS, the
oas parameter is not needed.
Convert OpenAPI 2.0 APIs to OpenAPI 3.0
SwaggerHub includes an OpenAPI 2.0-to-3.0 converter that lets you quickly convert your existing API definitions without having to update them manually.
|Note:||The converter works only for APIs, not for domains.|
To convert your API:
Open the API in the SwaggerHub editor.
From the dropdown next to the Save button, select Convert to OpenAPI 3.0.
— or —
openapi: 3.0.0(or any other valid
openapiversion) in the YAML code.
In the dialog that appears, click Convert & Update.
SwaggerHub will convert your API and save it as a new version with the -oas3 suffix. Your original API version will remain unchanged.
|Note:||Domains used by the API are not converted automatically. You will have to migrate the domains to the OpenAPI 3.0 format manually and then update the
How to tell if a definition uses OpenAPI 3.0 or 2.0?
The format is determined by the
swagger: "2.0" or
openapi: 3.0.x line in the API or domain definition (typically, this is the first line).
Besides, OpenAPI 3.0 definitions are displayed with the badge in MY hub, search results and in the editor. You can also search for and filter APIs and domains based on their format – OpenAPI 3.0 or 2.0.
Learn more about OpenAPI 3.0
To learn more about OpenAPI 3.0 keywords and features, see our OpenAPI 3.0 syntax guide.
The complete OpenAPI 3.0 specification is available on GitHub: