Restrictions on Swagger documents

IBM® Integration Bus has some restrictions on the Swagger documents that you can use to create a REST API that are in addition to the requirements that are specified in Swagger RESTful API Documentation Specification Version 2.0.

IBM Integration Bus supports version 2.0 of the Swagger specification. For information about Swagger, see Swagger. For information about version 2.0 of the Swagger specification, see Swagger RESTful API Documentation Specification Version 2.0.

IBM Integration Bus places certain restrictions on the format of Swagger documents that are used to create REST APIs:
  • The Swagger document must be saved in either JSON format with a .json file extension, or in YAML format with a .yaml or .yml file extension.
  • You must enter a value for the operationId field in the Operation Object, and the value of the operationId field must be unique across all operations that are defined in this REST API. IBM Integration Bus uses the operation ID as a unique name to refer to the operation.
  • The base paths of all REST APIs deployed to a single integration server must be unique. You cannot deploy a REST API to an integration server if there is already another REST API deployed with the same base path.
  • Form data parameters are permitted in Swagger documents by IBM Integration Bus, but no support is provided for parsing form data parameters.
  • The "file" JSON schema type is permitted in Swagger documents but is not supported by IBM Integration Bus; you cannot import a Swagger document that includes a reference to the "file" JSON schema type.
  • The JSON schema "$ref" keyword is supported with the following restrictions:
    • Only internal file references that have the form "$ref" : "#/definitions/Pet" are allowed.
    • Recursive self references can be imported into the IBM Integration Toolkit. However, if you use a Mapping node, the Graphical Data Mapping editor cannot be used to dynamically discover the depth of recursion. If recursive self references have been imported, use mapping only when you want to move the structure, by using a Move transform, from input to output.

When you are using a Swagger document in a message map, ensure that you satisfy the requirements described in JSON schema requirements for message maps.