Creating a REST API Descriptor from a Swagger Document

B2B Integration 10.4 | Administering and Monitoring B2B Transactions | Service Development Help | Working with REST API Descriptors | Creating a REST API Descriptor from a Swagger Document

Refreshing a REST API Descriptor

You can create REST API descriptors from external Swagger documents accessible through a URL, a REST resource on API Portal, or a REST resource residing in CentraSite. Keep the following in mind when creating a REST API descriptor from a Swagger document:

To create a REST API descriptor from a REST resource in CentraSite or API Portal, Designer must be configured to connect to CentraSite or API Portal.

The Swagger document that you use to create a REST API descriptor must be based on the Swagger Specification version 2.0.

Integration Server does not validate the contents of the external Swagger document and generates the assets based on the Swagger document used. Therefore, ensure that you validate the Swagger document before creating a REST API descriptor.

Designer supports only the following Swagger file formats: JSON and YAML.

To create a 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 dialog box, select the folder in which you want to save the REST API descriptor.

3. In the Element name field, type a name for the REST API descriptor 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 Select the Source Type dialog box, click Swagger Document and click Next.

6. In the Select the Swagger Document dialog box, select one of the following:

Select...	To...
API Portal	Generate a REST API descriptor from APIs present in the API Portal.
CentraSite	Generate a REST API descriptor from a REST resource available in CentraSite.
File/URL	Generate a REST API descriptor from a Swagger document that resides on the file system or on the Internet.
Import Swagger based on Tags	Group the operations defined in the Swagger document based on the tags. If you do not select this option, Designer groups the operations by path.

7. If you specified API Portal as the source, click Next and then under Select the API from API Portal list, select the API that you want to use to create the REST API descriptor.

8. If you specified CentraSite as the source, click Next and then under Select REST Resource from CentraSite, select the REST resource in CentraSite that you want to use to create the REST API descriptor.

9. If you specified File/URL as the source, do one of the following:

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.

Click Browse to navigate to and select a Swagger document on your local file system.

10. Click Finish.

Designer creates the REST API descriptor. Designer also creates the associated services (services), definitions (docTypes), and resources (resources) and places them under a folder that has the same name as the REST API descriptor appended with an underscore (_). The Properties view displays the source URL and source URI value for the REST API descriptor and its associated document type. For more information about the fields in the Properties view, see REST API Descriptor Properties.

Notes:

You cannot edit the elements, the general information in the General tab, or the MIME type of the REST API descriptor that you created. You can only edit the base path of the REST API descriptor and the service implementation of the services generated.

Do not edit, rename, or delete the services, docTypes, and resources folders, its subfolders, or the parent folder containing them all. Also, when you move the REST API descriptor to a different location in Designer, ensure that you move the corresponding folder containing the services, docTypes, and resources folders.