OpenAPI 3.0 Support

Last modified on October 20, 2021

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.

Considerations

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:

    • examples with externalValue,

    • multiple examples in header parameters,

    • using response links to initiate other operations.

    • automatic examples for oneOf and anyOf schemas. 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.

Create OpenAPI 3.0 definitions

Manually

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.

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.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:

  1. Open the API in the SwaggerHub editor.

  2. From the dropdown next to the Save button, select Convert to OpenAPI 3.0.

    — or —

    Change swagger: "2.0" to openapi: 3.0.0 (or any other valid openapi version) in the YAML code.

  3. In the dialog that appears, click Convert & Update.

  4. 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 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 OAS3 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.

OpenAPI version filter in SwaggerHub API catalog

Click the image to enlarge it.

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

See Also

OpenAPI 3.0 Tutorial

Highlight search results