Contact Free trial Login

OpenAPI Specification 3.0 Support Release Notes

June 26, 2020

Support for OpenAPI Specification (OAS) 3.0 is included in API Designer, Anypoint Exchange, and Anypoint API Community Manager.

You can create and edit API specifications in OAS 3. You can catalog existing OAS 3 API specifications to share with partners, customers, and developers in the platform or in internal and external API communities.

Products That Currently Support OAS 3 in Anypoint Platform

Currently, OAS 3 is supported only by the products in Anypoint Platform for the API lifecycle stages of design and publish.

API Lifecycle Stage Product OAS 3 Supported? Additional Information

Design

API Designer

Yes

Design

Anypoint Studio

Yes

Publish

Anypoint Exchange

Yes

Publish

Anypoint API Community Manager

Yes

Publish

REST Connect

Yes

In most cases, any OAS 3 features that REST Connect does not support are ignored and the connector is still generated. In some cases, a connector cannot be generated, and the user receives an error email explaining why a connector cannot be generated from the API specification. In all cases, API specifications are published normally from API Designer to Anypoint Exchange.

Implement

Anypoint Studio

No

Deploy

Mule runtime engine

No

Operate

API Manager

No

Current Limitations of OAS 3 Support

Currently, you cannot directly implement, deploy, or operate APIs using native OAS 3 specification formats in the Anypoint Platform. To work around this limitation, convert the OAS 3 specification to RAML or OAS 2, then deploy or implement it.

Importing and managing OAS 3.0 components as Exchange dependencies inside a specification is currently not supported.

Currently, Anypoint Platform does not support converting OAS 3 APIs to OAS 2, so a third-party tool is used for this conversion, as described in the following section.

Convert Specifications

The RAML and OAS specification standards have some differences. RAML has constructs such as resource types, traits, overlays, and more which do not exist in OAS. Similarly, OAS 3 has constructs such as server-templating, links, callbacks, and more which do not exist in RAML. The conversion between these standards is best effort only.

Convert to RAML

When you upload an OAS 3 specification to Anypoint Exchange, it automatically generates a RAML version.

To convert an OAS 3 API specification to RAML in API Designer:

  1. Import the OAS 3 API specification to API Designer.

  2. Click the three dots next to the filename in the Files pane and select Duplicate as…​.

  3. In the Duplicate As dialog, select RAML.

  4. Set the root file of the project to the RAML version of the API specification.

You can use the converted RAML specification in Anypoint Studio and API Manager.

Convert to OAS 2

Currently, Anypoint Platform does not support converting OAS 3 APIs to OAS 2. To convert an API from OAS 3 to OAS 2, download the OAS 3 specification and convert it using a third-party or open-source tool, such as APImatic Transformer. You can upload the converted OAS 2 specification to Exchange.

Converting an asset in API Designer creates a new version of the asset in Exchange and does not create a second duplicate asset in Exchange. Downloading an asset from Exchange, converting it by using a third-party tool such as APIMatic Transformer, and uploading the converted asset back to Exchange does create a second duplicate asset in Exchange. It is best to have no duplicate assets. However, only third-party tools can convert OAS 3 to OAS 2.

Work with OAS 3 APIs in API Designer

API Designer supports these actions with OAS 3 APIs:

  • Create API specifications in OAS 3.

    When creating a new API-specification project, select OAS 3.0 in the Language field.

  • Import OAS 3 specifications from Anypoint Exchange or from your filesystem:

    Options for importing
    Figure 1. How to import files into an API-specification project in API Designer
    1. Click the gear icon in the top-right corner of the text editor.

    2. Select either of these options:

      • Select Import from Exchange to see both of these lists:

        • A list of the API specifications that are available from the business organization that your user ID belongs to in Anypoint Platform

        • A list of the API specifications that are published by MuleSoft

      • Select Import to import an API specification from your local filesystem.

  • Develop and edit OAS 3 specfications.

  • View documentation that is included in OAS 3 API specifications.

  • Simulate calls to methods that are in OAS 3 API specifications by activating the mocking service.

  • Publish OAS 3 API specifications to Anypoint Exchange.

Work with OAS 3 APIs in Anypoint Exchange

Exchange supports these actions with OAS 3 APIs:

  • Publish an existing OAS 3 API specification.

    On the Publish a new asset page, select REST API - OAS in the Asset type field.

    The API is now visible to Exchange users, and the users can explore the documentation and specification as with any other API, including the original OAS 3 specification and the generated RAML specification.

  • Download OAS 3 API specifications as RAML API specifications for scaffolding and implementation with third-party IDEs.

Work with OAS 3 APIs in API Community Manager

Publish APIs written in OAS 3 and cataloged in the platform into your API communities.

OAS 3 APIs are presented to your target audiences the same way as RAML and OAS 2 APIs, so that your audiences can discover, learn, and consume the APIs seamlessly, regardless of the specification language.

Was this article helpful?

💙 Thanks for your feedback!