Creating a Consumer REST API Descriptor from a Swagger Document

Software AG Products 10.7 | Service Development Help | Working with REST API Descriptors | Swagger Based Consumer REST API Descriptors | Creating a Consumer REST API Descriptor from a Swagger Document

You can create a consumer REST API descriptor (RAD) from:

External Swagger document accessible through a URL

A REST API on API Portal

A REST resource/service residing in CentraSite

Keep the following in mind when creating a consumer RAD from a Swagger document:

The Swagger document that you use to create a consumer RAD must be based on the Swagger Specification version 2.0.

To create a consumer RAD from a REST resource/service in CentraSite or from a REST API on API Portal, configure Designer to connect to CentraSite or API Portal.

Ensure that you use a valid Swagger document before creating a consumer RAD.

If the Swagger document that is used to create the consumer RAD is linked to a provider RAD and if you change the service signature of any service in the provider RAD, then you must refresh the consumer RAD to synchronize the service signature details in the consumer RAD. To refresh the RAD, see Refreshing a REST API Descriptor .

Following are the supported components from the Swagger Specification version 2.0:

MIME types: application/xml, text/xml, application/json

Protocol: http, https

Authentication mechanism: BASIC

Note:
If the Swagger document contains unsupported authentication mechanisms and MIME types, then Integration Server generates the assets including all these fields while creating the RAD; however, does not support these unsupported fields at run time.

To create a consumer REST API descriptor from a Swagger document

1. In the Service Development perspective of Designer, select File > New > REST API Descriptor.

2. In the Create a New REST API Descriptor wizard page, select the folder in which you want to save the RAD.

3. In the Element name name field, type a name for the RAD using any combination of letters, numbers, and the underscore character. For more information about restricted characters, see Guidelines for Naming Elements.

4. Click Next.

5. In the Specification Version wizard page, select Swagger 2.0 as the specification version of the source. Click Next.

6. In the Select the Source Type wizard page, select Consumer and click Next.

7. In the Select the Swagger Document Location wizard page, select one of the following to perform the corresponding action in Designer:

Source Location	Purpose	Course of Action
API Portal	Generate a RAD from APIs present in the API Portal.	Click Next and then in Select the API from API Portal list, select the API that you want to use to create the RAD.
CentraSite	Generate a RAD from a REST resource/service available in CentraSite.	Click Next and then in Select REST Resource from CentraSite, select the REST resource in CentraSite that you want to use to create the RAD.
File/URL	Generate a RAD from a Swagger document that resides on the file system or on the Internet.	Do one of the following: Click Browse to navigate to and select a Swagger document on your local file system. Enter the URL for the Swagger document. The URL should begin with http:// or https://. Provide your username and password to use the Swagger document from the website.

8. You can choose the REST operations from the selected Swagger document. Based on your selection, Designer adds the REST operations in the generated RAD. If you want to choose the REST operations from the Swagger document, click Next and select one or more REST operations; otherwise, click Finish.

Designer creates the consumer RAD. It also creates the associated REST connector services (under connectors folder) and document types (under docTypes folder) and places the connectors and docTypes folders under a folder that has the same name as the RAD appended with an underscore (_).

The Properties view displays the source URL and source URI value for the RAD and its associated document type. For more information about the fields in the Properties view, see REST API Descriptor Properties.

Note:

Do not rename or delete the docTypes folder, connectors folder and subfolders, or the parent folder. Also, if you move the RAD to a different location in Designer, move the associated folders as well.

If a RAD is created in earlier versions and is moved, renamed, or copied to a different location, then you must refresh the RAD. Otherwise, the connector services might not work as expected.

If there is any change in the Swagger document, you can refresh the RAD in Designer. For more information, see Refreshing a REST API Descriptor .