Open API (Swagger) Adapter

Swagger is a powerful open API specification framework backed by a large ecosystem of tools that helps you design, build, document, and consume your RESTful APIs.

To configure an OpenAPI (Swagger) service in Kony Fabric, a JSON or YAML file(s) (with all dependent OpenAPI (swagger) files or a single specification file) must be created which defines all the APIs and schemas. When an OpenAPI (swagger) service is created and configured, the system retrieves the meta data from the imported single or the dependent JSON or YAML file(s) and displays the APIs of that file.

Kony Fabric parses the JSON or YAML file(s) and exposes all the endpoints through the integration service.

Configure Open API (Swagger) End-point Adapter

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

1. In the Name field, provide a unique name for your service. When you enter the name, the name is updated for the active service under the Services section in the left pane.
2. From the Service Type list, select Open API (Swagger).

   Note: XML is selected, by default.

3. Provide the following details to create a Open API (Swagger) service.

   Fields	Description
   Version	Select the version for the service.
   Connection Parameters	Click Upload to upload a JSON or YAML file(s) with OpenAPI(swagger) specifications.
   Host URL	The host URL available in the uploaded swagger file is displayed here. You can change this URL if required. If you change the host URL, the updated URL will be honored over the URL available in the uploaded file.
   Base Path	The base path available in the uploaded swagger file is displayed here. You can change this path if required. If you change the base path, the updated path will be honored over the path available in the uploaded file.
   Authentication	Select an existing Identity Provider from the drop-down list.
   Web Service Authentication	Select one of the following modes: None: Select this option if you do not want to provide any authentication for the service. Basic: Provide User ID and Password if the external Web service requires a form or basic authentication. NTLM: Your service follows the NT LAN Manager authentication process. You are required to provide the User ID, Password, NTLM Host, and NTLM Domain.

4. For additional configuration of your service definition, provide the following details in the Advanced section.

   Field	Description
   Custom code	To specify a JAR associated to the service, select one from the Select Existing JAR drop-down menu or click Upload New to add a new JAR file. Make sure that you upload a custom JAR file that is built on the same JDK version used for installing Kony Fabric Integration. You can download the uploaded jars to your local system.
   API Throttling	If you want to use API throttling in Kony Fabric Console, to limit the number of request calls within a minute. do the following: In the Total Rate Limit text box, enter a required value. This will limit the total number of requests processed by this API. In the Rate Limit Per IP field, enter a required value. With this value, you can limit the number of IP address requests configured in your Kony Fabric console in terms of Per IP Rate Limit. To override throttling from Kony Fabric App Services Console, refer to Override API Throttling Configuration.

   Note: All options in the Advanced section are optional.

5. Enter the Description for the service.
6. Click SAVE to save your service definition.

Create Operations for Open API (Swagger)

The Operations List tab appears only after the service definition is saved.

Note: Click Operations List tab > Configure Operation. The Configured Operations list appears.

To create an operation, follow these steps:

1. Click SAVE & ADD OPERATION in your service definition page to save your service definition and display the NewOperation tab for adding operations.
                       OR
   Click Add Operation to add a new operation or from the tree in the left pane, click Add > Add New Operation.

2. Under Operation List tab. expand the Please Select drop-down list. Based on the uploaded JSON or YAML file, all the supported operations will be displayed.
3. Expand the uploaded OpenAPI (swagger) file and under Services, the paths of the uploaded swagger file is exposed. When a particular path / operation is selected, all the fields under the corresponding is populated.

   

4. Click ADD OPERATION. The system adds your operation to the Operations List page.

   

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

   

6. The system displays the selected operation in the edit mode. Provide the following details to configure the operation.

   Field	Description
   Name	The operation name appears in the Name field. You can modify the name, if required.
   Operation Security Level	It specifies how a client must authenticate to invoke this operation. Select one of the following security operations in the Operation Security Level field. 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. Note: The field is set to Authenticated App User, by default. For more details, refer Security Level.

7. For additional configuration of request (or) response operations, provide the following details in the Advanced section.

   Custom Code Invocation	When you test, the services details of various stages in the service execution are presented to you for better debugging. All options in the Advanced section are optional. For more details, refer to Preprocessor and Postprocessor. Note: The Pre and post-processing logic feature is not supported for a Swagger service.
   Additional Configuration Properties	Additional Configuration Properties allows you to configure service call time out cache response. For information on different types of configuration properties, refer Properties.
   Front-end API	Front-end API allows you map your endpoint (or) backend URL of an operation to a front-end URL. For detailed information, refer Custom Front-end URL.
   Server Events	Using Server Events you can configure this service to trigger or process server side events. For detailed information, refer Server Events.

   Note: All options in the Advanced section for operations are optional.

8. Enter the Description for the operation.

Configure Request Operation for Open API (Swagger)

The request input parameters are picked from the uploaded OpenAPI definition file and any changes made are ignored. Make sure that the input parameters are form-url-encoded.

You can perform the following actions in Request Input tab:

1. Under the Body tab, perform the following actions:
   1. To configure parameters in the clients body, do the following:

      Field	Description
      Name	Enter the name for the request input parameter. field contains a unique identifier for a parameter.
      TEST VALUE	Enter a value. A test value is used for testing the service.
      DEFAULT VALUE	Enter the value, if required. The default value will be used if the test value is empty.
      SCOPE	Select request or session. This field is set to Request, by default. The default datatype for the selected column is loaded under DATATYPE field.
      DATA TYPE	Select a data type in the DATA TYPE field. String is 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 number. Note: For any operation in OpenAPI (Swagger), the binary data is not supported.
      Record ID	For nested payloads the RECORD ID is populated.
      Collection ID	For arrays, the Collection ID is displayed.
      Description	Enter a description for the Request Input.

2. To validate the provided details, you must test the service operation. You can refer to Test a Service Operation for the steps to test a service.

Configure Response Operation for Open API (Swagger)

Click the Response Output tab to view the output test values, such as name, scope, and data type.

The Restrict Parameters to OpenAPI definition check-box is selected by default. It makes sure that the OpenAPI definition provided is used as the source for the Response output parameters. You cannot change the output parameters.

If you want to choose the required output parameters that you want to show in the response manually, you have to deselect Restrict Parameters to OpenAPI definition check-box, select the required environment from the Select Environment list, and then click Save and Fetch Response. The back-end response of the service appears.

In the response, the Test > Backend Response pane displays the nodes that will be added to the response output in a Tree view. You can do the following to select the required nodes that you want to show in the response from here:

1. Click or hover on the required node which you want to add in the response output.

   The Create response button appears next to that node.

2. Click Create response.

   

   A new row is created automatically in the Response Output tab and the details of the selected node are added to it.
3. You can also check the JSON response, click Add Parameter, and write the JSON path of the required output parameter manually.

Note: If you define parameters inside a record as the session, the session scope will not get reflected for the parameters.

To validate the details, select an environment from the Select Environment list and click Save and Fetch Response. The result of the operation appears. For more details, refer Test a Service Operation.

Note: For nested payloads, you cannot test the service from Kony Fabric Console in the case of Post/Put methods. You can only send a request through Admin Console or postman.

Click SAVE OPERATION.

Note: Following are few limitations to be followed before using OpenAPI (Swagger):

- Only OpenAPI (Swagger) 2.0 is supported.

- If any scheme is not specified in your swagger file, by default HTTPS will be considered.

- If an authentication is linked to your swagger file, you must define it at each operation level under security tag.

Note: You can view the service in the Data Panel feature of Kony 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.

 

Copyright © 2020 Kony, Inc. All rights reserved.