OpenAPI 3.0 Support
SwaggerHub supports OpenAPI 3.0 (OAS3), a major revision of OpenAPI 2.0 (formerly known as Swagger). OpenAPI 3.0 introduced 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 updating them manually.
Considerations
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:
examples with
externalValue,multiple
examplesin header parameters,using response links to initiate other operations.
automatic examples for
oneOfandanyOfschemas. A workaround is to add schema examples manually:oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' example: petType: dog name: Rex
AWS Lambda and IBM API Connect integrations do not support OpenAPI 3.0.
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.
OpenAPI 3.0 APIs cannot be converted to AsyncAPI.
Create OpenAPI 3.0 definitions
Manually
When you create a new API or domain, use the Specification combo box to choose the definition format – OpenAPI 3.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.
Programmatically
You can also create and update APIs programmatically, for example, using SwaggerHub CLI or Registry 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.yamlIn 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 updating 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 —
Change
swagger: "2.0"toopenapi: 3.0.0(or any other validopenapiversion) 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 $ref values in the API.
How to tell if a definition uses OpenAPI 3.0?
The format is determined by the swagger: '2.0', openapi: 3.0.0 or asyncapi: '2.x.x' line in the API or domain definition (typically the first line).
OpenAPI 3.0 definitions are displayed with the 
badge in MY hub, search results, and editor. You can also search for and filter APIs and domains based on their format – OpenAPI 3.0, 2.0, or AsyncAPI.
 |
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:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md