OpenAPI 3 Data Sources FAQ¶

JSON and XML data sources support OpenAPI 3 as a convenient way of importing service operations as base views (see JSON Sources and XML Sources). This is a compilation of information that can be useful when using OpenAPI 3 in XML and JSON data sources.

• OpenAPI 2. OpenAPI 2 / Swagger documents are not directly supported, but usually you will be able to convert an OpenAPI 2 / Swagger document into OpenAPI 3. Before the conversion, it is good practice to validate the OpenAPI 2 / Swagger document, and convert it into YAML (if not already in YAML format) using the Swagger Editor. It may be necessary to tweak the OpenAPI 2 / Swagger document before it is completely valid and can be converted into OpenAPI 3 without errors. To convert from version 2 to version 3, paste the OpenAPI 2 specification in the Swagger Editor and click Edit > Convert To OpenAPI 3 (there are other conversion tools, choose any tool that works well for you).

• Loading default values from the OpenAPI 3 document. The Default configuration for base views > Configure > Load default values from OpenAPI3 Specification button found in JSON and XML data source wizards configured to use OpenAPI 3 retrieves the base URI defined by the OpenAPI 3 document. There are some special cases to consider:

  • Relative URIs. If the base URI defined by the OpenAPI 3 document is relative, users must add the actual host name to the URI (or, if this option is available, modify the URI directly in the OpenAPI 3 document before importing it).

  • URIs with variables. OpenAPI 3 documents may define base URIs with variable references (e.g. https://url.{var}.com), which must be manually replaced by a specific value. The list of possible values can be found in the OpenAPI 3 document (you can use the Swagger Editor in order to easily check the available options).

• Required HTTP headers. Some services require specific HTTP headers in every request. The XML and JSON data source wizards will automatically add to the configuration the Accept and Content-Type headers with appropriate values. Other HTTP headers required by the service must be manually added in Default configuration for base views > Configure > HTTP headers.

• Some operations cannot be imported as base views. It is possible that some service operations defined by an OpenAPI 3 document cannot be imported as base views (these operations will show a tooltip in the introspection tree describing the specific reason for this). There are two main reasons for this:

  • The operation cannot return a data type compatible with the data source (JSON or XML).

  • The response schema and/or the body schema defined for the operation are not supported and cannot be converted into a Virtual DataPort view schema. For example, the keywords “oneOf” and “anyOf” that reference multiple schemas are not supported by VDP, as well as Free-form objects.

• Accessing the OpenAPI 3 document requires custom headers or an unsupported authentication scheme. Currently, it is not possible to define custom HTTP headers, or authentication schemes different to HTTP Basic / Digest, in order to access remote OpenAPI 3 documents. In this case, you can download the OpenAPI 3 document from the service’s website and configure local access.