OpenAPI 3.0 support in IBM API Connect

From Version 2018.4.1.4, IBM® API Connect supports the OpenAPI 3.0 specification, with some limitations.

Overview

A Product can contain any combination of OpenAPI 2.0 and OpenAPI 3.0 APIs. When you publish a Product that contains an OpenAPI 3.0 API, that API is validated to ensure that it is syntactically correct, and that references to configuration resources and policies resolve correctly, in the same way that OpenAPI 2.0 APIs are validated.

You can also validate OpenAPI 3.0 APIs in your local file system by using the apic validate command provided by the developer toolkit CLI; for details, see Validating the YAML or JSON definition of an API or Product.

If you retrieve an API object by using the developer toolkit CLI or the API Connect REST APIs, there is an oai_version property that defines which OpenAPI version the API represents.

There is no OpenAPI 3.0 API support with the DataPower® Gateway (v5 compatible); OpenAPI 3.0 API support is provided by the DataPower API Gateway only.

Limitations

The limitations to the OpenAPI 3.0 support in IBM API Connect are as follows:

  • User interface limitations.
    • There is no support for working with draft OpenAPI 3.0 APIs in the API Manager or API Designer user interfaces. You must stage or publish OpenAPI 3.0 APIs directly by using the apic products:publish developer toolkit CLI command, or the API Connect REST APIs.
    • There is no support for editing OpenAPI 3.0 APIs in the API Manager user interface.
    • There might be some rendering errors in the Developer Portal test tool when OpenAPI 3.0 examples or schemas are displayed.
  • Developer toolkit limitations.
    • You cannot create a draft API on a management server by uploading a local OpenAPI 3.0 API definition file with the apic draft-apis:create command. You can, however, stage or publish OpenAPI 3.0 APIs directly by using the apic products:publish developer toolkit CLI command, or the API Connect REST APIs.
  • General limitations.
    • The servers array cannot contain more than one server.
    • The url entry in the servers array cannot contain variables.
    • path objects cannot contain server object overrides.
    • Wildcarding in response objects is not supported for error codes or success codes.
    • There is no support for converting a WSDL defined SOAP service into an OpenAPI 3.0 API.
  • Security.
    • The following security schemes are not supported:
      • HTTP JWT Bearer (HTTP Basic scheme is supported).
      • OAuth2 with multiple flows (a single flow is supported).
      • OpenID Connect (OIDC).
    • The use of cookies in an API key is not supported.
  • Assembly policies.
    • Only the following policies are supported:
      • invoke
      • jwt-generate
      • jwt-validate
      • oauth
      • throw
      • user-security
    • The validate and map policies are not supported.
    • Schema support is limited to Draft 4 and earlier. Therefore, the following policies are limited to those drafts:
      • gatewayscript
      • set-variable
      • switch
      • json-to-xml
      • xml-to-json
      • parse
      • xslt

      For draft specification details, see https://json-schema.org/specification-links.html.