Create from a Swagger Definition
Creating Connector from a Swagger Definition
Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document, and consume REST APIs.
Swagger allows you to describe the structure of your APIs so that your machines can read them. Swagger does this by asking your API to return a YAML or JSON that contains a detailed description of your entire APIs.
This tutorial helps you to create a Connector for petstore swagger, define the predefined operations, and test them for a RESTful API using the webMethods platform.
Below is the video tutorial for Creating Connector from a Swagger Definition:
Creating Connector Project
- Launch Software AG Designer and change the perspective to CloudStreams Development
In Software AG Designer, go to Window > Perspective > Open Perspective > CloudStreams Development
- Open CloudStreams Providers view
- Configure the Integration Server(IS) if not configured
- Right-click on the Integration Server Name(Default) and select Cloudstreams Provider Project
- Enter the Project name and choose Connector Type as REST
Example: DemoPetStoreProvider
- Enter the Connector Details for Petstore
Example:
Name: Petstore
ID: com.softwareag.cloudstreams.petstore_v2
Group: Petstore
Import Swagger specification file: checked
File/URL: https://petstore.swagger.io/v2/swagger.json
7. Click the Finish button. All the resource definitions which are part of the Swagger file are generated as part of the Connector as shown in the below screenshot:
Adding Authentication
Note:- Petstore Swagger supports API Key, OAuth2, and also works without authentication. This example demonstrates the authentication mechanism in the Connector when you choose the authentication type as Credentials.
- In Designer, expand the project name and double-click the Connector name Petstore to show the overview of the Connector
- On the Connection screen select the Authentication tab and choose the Authentication Type as Credentials and save the changes
For your reference, click here to download the sample Connector project created using the above steps. To know how to import the Connector project into Designer CloudStreams Development, go to Appendix.
Publishing Connector
Finally, let us publish the Connector after all the resources are generated for the CRUD operations.
To create the Connector project as IS package you need to publish it to the target server(IS).
Follow the below steps to publish the Connector:
- Right-click the Connector project in the CloudStreams Providers view and click Publish
- Ensure that the Connector project is selected and click Next
- Select the Target Server(IS) and click the Finish button
For your reference, click here to download the sample IS package for the Connector.
Creating Predefined Operations
Each application has the most commonly used objects and their related REST resources/operations.
Predefined operations enable end-users to directly consume these most widely used operations.
Example: Create a ticket in ServiceNow
Follow the below steps to create predefined operations:
- Create a connection for the published Connector. You can follow the below steps to create a Connection:
Go to Integration Server Administrator page > Solutions > CloudStreams > Providers > Petstore
Click the connector name Petstore from the Connectors List and select Configure New ConnectionProvide the Connection Details such as Package, Folder name, Connection name, Credentials, and Authorization Type
Example:
Package: Default
Folder Name: CloudConnections
Connection Name: PetstoreConnection
Username: demo
Password: demo
Authorization Type: basic
- Create a folder structure under the DemoPetStoreProvider package for creating Predefined operations under them.
In Software AG Designer, go to Service Development perspective > Expand the Package(DemoPetStoreProvider) > Right-click the package and create the folder structure as shown below:
- Create a Cloud Connector Service (CCS) with the name findPetsByStatus
In Software AG Designer, go to Service Development perspective > Expand the Package > Right-click the triggers folder and perform the action as shown below:
- Choose Finds Pets by status Resource
- Create an empty folder findPetsByStatus with the same name as CCS
- Create an empty FlowService findPetsByStatus with the same name as CCS within the created folder as shown below:
- Open the empty FlowService and click the Tree tab and then drag and drop the CCS on the canvas
- Click the Input/Output tab of the FlowService
- Open CCS, go to the Input/Output tab and copy the entire Input parameters from the CCS's Input tab and paste them into the FlowService's Input tab
- Similarly, copy entire Output parameters from CCS's Output tab and paste them into the FlowService's Output tab
- Open the FlowService, click the Tree tab, and select the dropped CCS on the canvas.
In the below Pipeline tab, check if the variables are correctly mapped, if not then manually map the variables
The predefined operation is now ready and you can run the created FlowService. Repeat the above steps starting from Step 3 to add more predefined operations.
For your reference, click here to download the Connector IS Package with the created predefined operations.
Testing Connector
To test the predefined operations created using the Connector package, follow the below steps.
To test a Connector either use the above-created Connector package or download the Connector package from here
Create a test package(DemoPetStoreProviderTest) that encloses the connections and testing artifacts as shown below:
- Create a folder inside the package with the same name(DemoPetStoreProviderTest) to avoid any namespace conflicts
- Right-click the folder DemoPetStoreProviderTest and create folder connections to keep all your connections to the SaaS backend
- Create a connection similar to Creating Predefined Operations (Step 3) in the DemoPetStoreProviderTest package under connections folder. Provide the connection folder name as DemoPetStoreProviderTest.connections
- Copy the connection name as shown in the below image which will be used as input to test the Predefined operation
- Create folder services for all FlowServices that you will create to test the predefined operations
- Create a FlowService findAvailablePets, drag and drop the predefined operation findPetsByStatus from the Connector package as shown below, and save the changes
- Select the dropped predefined operation in the FlowService and click the Pipeline to show the parameters and $connectionAlias
- Copy the entire Service In input parameters as shown below:
- Click the Input/Output tab of the FlowService and paste the input parameters.
Repeat the same for the output parameters
- Right-click the FlowService findAvailablePets and run the service as shown below:
- Provide the inputs for parameters as below and click OK
status: available
$connectionAlias: value copied from Testing Connector (Step 6)
The HTTP call is made and the response from Petstore is shown in the Results tab.
Here, you can verify the status and response of the executed operation.
Ensure that all the required fields are present as per the signature of the created Predefined Operation.
Congratulations! You have successfully created the Connector.
To download the source code of the Petstore Connector from GitHub, click here.
Connector Submission to Software AG
Now that you have the Connector ready, you might want to submit the Connector package to Software AG.
Software AG will review the Connector, and if it meets the certification criteria,
then it will be published to webMethods.io Integration Platform.
Go to Connector Certification page to submit.