OpenAPI 3.0 Support

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

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

  • 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

  • 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 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 "http(s)://api.swaggerhub.com/apis/MyOrg/MyApi"
     -H "Authorization: YOUR_API_KEY"
     -H "Content-Type: application/yaml"
     --data-binary @./path/to/myapi.yaml

Convert OpenAPI 2.0 APIs to OpenAPI 3.0

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

  1. Open the API in the API Hub for Design editor.

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

    convert-to-oas-3.png

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

    oas-3-conversion-prompt.png

  4. API Hub for Design will convert your API and save it as a new version with the -oas3 suffix. Your original API version will remain unchanged.

    converted-spec.png

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 OAS3 badge in My APIs, 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 below:

https://swagger.io/specification/v3/

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md

See Also

In this section:
© 2024
Publication date: