OpenAPI (Swagger) Adapter

The OpenAPI Specification (formerly: Swagger specification) is a framework that is used to define interfaces, with which you can design, build, document, and consume REST APIs.

To configure an OpenAPI (Swagger) service in Quantum Fabric, you need a JSON or a YAML file (with any dependent files) that contains specifications for the required APIs. The service retrieves the metadata from the imported JSON or YAML files and displays the APIs.

From V9 ServicePack 2, Quantum Fabric supports OpenAPI 3.0. For more information about OpenAPI 3.0, you can refer to the following articles:

Configuring an OpenAPI (Swagger) End-point Adapter

To configure a OpenAPI (Swagger) adapter in Integration Service Definition tab, follow these steps:

  1. On the Integration Service Definition page, from the Service Type list, select OpenAPI (Swagger).
  2. Configure the service definition parameters. For more information, refer to the following sections.
    ParameterDescription

    Name

    Specifies the name that Fabric uses to identify the service on the console.

    Version

    Specifies the version number of the service. The version number ranges from 1.0 to 999.99.

    If you are creating a new service, the version number is 1.0 by default, and it cannot be changed.

    Description

    Specifies the description of the service that is displayed on the console.

  3. After you configure all the parameters, click SAVE.

    NOTE: If you want to add operations to the service, click SAVE AND ADD OPERATIONS.

Creating Operations for OpenAPI (Swagger)

After you create a service, you can view the existing operations and also create operations on the Operations List tab. For an OpenAPI endpoint, the operations are the paths that are defined in the Swagger file, for example: addPet or updatePet.

To create an operation, follow these steps:

  1. From the Service Definition page, switch to the Operations List tab.
    Alternatively, click the plus (+) icon on the left pane, and then click Add New Operation.
  2. On the Operations List tab, from the drop-down list, select the operations that you want to add to the service.
    When you select a path (operation), all the corresponding fields of the operation are populated.

  3. After you select the operations, click ADD OPERATION. Fabric adds the selected operations to the Operations List tab.

  4. Under Configured Operations, click an operation to view the details of the operation.

    Fabric displays the selected operation in the edit mode. You can configure the parameters to update the operation. For more information, refer to the following table.

    FieldDescription

    Name

    Specifies the name that Fabric uses to identify the operation on the console.

    Operation Security Level

    Specifies the authentication that is required to invoke the operation. Contains the following options:

    • Authenticated App User – It restricts the access to clients who have successfully authenticated using an Identity Service associated with the app.
    • Anonymous App User – It allows the access from trusted clients that have the required App Key and App Secret. Authentication through an Identity Service is not required.
    • Public – It allows any client to invoke this operation without any authentication. This setting does not provide any security to invoke this operation and you should avoid this authentication type if possible.
    • Private - It blocks the access to this operation from any external client. It allows invocation either from an Orchestration/Object Service, or from the custom code in the same run-time environment.

    Description

    Specifies the description of the service that is displayed on the console.

  5. Configure the parameters in the Advanced section based on your requirement. For more information, refer to the following table.

  6. After you configure the required parameters, click SAVE.

Configuring Request Parameters

The request input parameters are picked from the uploaded OpenAPI specification file. Any changes that are made to the parameters from the console are ignored.

IMPORTANT: Make sure that the input parameters are form-url-encoded.

To create a new parameter on the Request Input tab, follow these steps:

  1. On the Body tab, click Add Parameter. A new row is added to the table of parameters.
  2. Configure the fields (columns) for the input parameter. For more information, refer to the following table.
    FieldDescription

    Name

    Specifies a unique identifier for the parameter. The name is the key of the parameter in the request.

    VALUE

    Specifies the source of the value of the parameter. Contains the following options.

    • request
      The value is picked from the configuration of the request parameter. If you select request as the source, you need to configure the TEST VALUE and DEFAULT VALUE fields.
    • session
      The value is picked from the session context. If you select session as the source, the TEST VALUE and DEFAULT VALUE fields are disabled.
    • constant
      The value is a constant that is defined on the Fabric console. If you select constant as the source, you need to type a value for the parameter.
    • identity
      The value is picked from the response that is sent by the specified identity provider. If you select identity as the source, you need to configure the provider, attribute, and value. For example: sampleAuth.profile.userID
    • NOTE: For more information on Externalizing Identity Services, refer to Replace the Identity Service references in a Fabric app.

    TEST VALUE

    Specifies the value of the parameter that is used while testing the service.

    DEFAULT VALUE

    Specifies the value of the parameter that is used if the test value is empty.

    DATA TYPE

    Specifies the data type of the parameter. Contains the following options:

    • string
      A combination of alpha-numeric and special characters. Supports all formats (including UTF-8 and UTF-16) with no maximum size limit.
    • boolean
      A value that can be true or false.
    • number
      An integer or a floating point number.
    • date
      A value that contains the day, month, year, and time.
    • collection
      A set of multiple records.
    • record
      A set of multiple objects.

    NOTE: The binary data type is not supported for operations in OpenAPI (Swagger).

    Record ID

    Specifies the ID of the record that contains the parameter. This field is applicable for nested payloads.

    Collection ID

    Specifies the ID of the collection that contains the parameter. This field is applicable for nested payloads.

    Description

    Specifies the description for the request parameter.

  3. After you configure all the parameters, you can validate the details by testing the service operation. For more information, refer to Test a Service Operation.

Configuring Response Parameters

You can view the details (such as name, scope, and data type) for the response parameters on the Response Output tab.

The Restrict Parameters to OpenAPI definition check box is selected by default. The check box specifies whether parameters are picked from the OpenAPI definition file or the Fabric console configuration.

To create a parameter based on the back-end response, follow these steps:

  1. Clear the Restrict Parameters to OpenAPI definition check box.
  2. From the Select Environment list, select a run-time environment, and then click Save and Fetch Response.
    The back-end response of the service appears in the Test window. The Backend Response pane displays the nodes of the response in a Tree view.
  3. Point to the node that you want to add to the response output parameters, and then click Create response.

    A new row is created on the Response Output tab and the details of the selected node are added to it.

To create a parameter manually, follow these steps:

  1. Clear the Restrict Parameters to OpenAPI definition check box.
  2. Click Add Parameter. A new row is added to the parameters table.
  3. Configure the fields for the parameters. For more information, refer to the following table.
    FieldDescription

    Name

    Specifies a unique identifier for the parameter. The name is the key of the parameter in the response.

    Scope

    Specifies the scope at which the parameter is available. Contains the following options.

    • response
      The parameter is available in the response.
    • session
      The parameter is available throughout the user session.

    NOTE: If the parameters inside a record are defined as the session, the session scope is not reflected for the parameters.

    DATA TYPE

    Specifies the data type of the parameter. Contains the following options:

    • string
      A combination of alpha-numeric and special characters. Supports all formats (including UTF-8 and UTF-16) with no maximum size limit.
    • boolean
      A value that can be true or false.
    • number
      An integer or a floating point number.
    • date
      A value that contains the day, month, year, and time.
    • collection
      A set of multiple records.
    • record
      A set of multiple objects.

    NOTE: The binary data type is not supported for operations in OpenAPI (Swagger).

    Record ID

    Specifies the ID of the record that contains the parameter. This field is applicable for nested payloads.

    Collection ID

    Specifies the ID of the collection that contains the parameter. This field is applicable for nested payloads.

    Description

    Specifies the description for the request parameter.

  4. After you configure all the parameters, click SAVE OPERATION.

    NOTE: If you want to test the operation, select a run-time environment from the drop-down list, and then click SAVE AND FETCH RESPONSE.

NOTE: You can view the service in the Data Panel feature of Quantum Visualizer. By using the Data Panel, you can link back-end data services to your application UI elements seamlessly with low-code to no code. For more information on Data Panel, click here.

Testing the Operation

After you create an operation and configure the request and response parameters, you can test the operation and validate the details that you configured.

To test an operation, select an environment from the Select Environment list, and then click SAVE AND FETCH RESPONSE. The result of the operation appears. For more details, refer Test a Service Operation.

NOTE: For Post or Put methods that contain nested payloads, you cannot test the service from the Quantum Fabric Console. You can only send a request from the App Services Console, or from Postman.

Miscellaneous

Swagger 2.0 in Quantum Fabric

  • If the Swagger file does not specify a scheme, HTTPS is picked by default. If the file specifies both HTTP and HTTPS schemes, HTTP is picked.

OpenAPI 3.0 in Fabric V9 ServicePack 2

  • With the OpenAPI 3.0 Specification, you can add multiple URLs to your definition and also include parameters in the URL. For more information, refer to A Visual Guide to What's New in Swagger 3.0.
    • While creating a service for OpenAPI 3.0 in Quantum Fabric V9 ServicePack 2, you can select only one URL as the Server URL. If your specification file contains multiple URLs, Fabric picks the first URL by default.
    • You can change the URL before you publish the service to the run time by reconfiguring the service before a publish. For more information, refer to Service Reconfiguration.
    • Parameters in the URL are not supported. Make sure that you add static server URLs to your specification file.
  • The trace HTTP method is not supported and the APIs that use the trace method are ignored.
    APIs that use other HTTP methods are parsed by Fabric to create operations.
  • If the HTTP response code is not 200, the console displays the response from the back-end server as is.
  • OpenID Connect (OIDC) is not supported for authentication.
  • Callbacks, which are used to define Webhooks, are not supported. Links, which are used to define the output one operation as input for another operation, are not supported. Make sure that you remove Callbacks and Links from your OpenAPI 3.0 spec before you upload it to Fabric.
  • Serialization of parameters, which includes style (defines the delimiter for multiple parameters) and explode (specifies whether objects of an array are generated as separate parameters), is not supported.
  • Fabric does not parse or validate examples from the specification file.