Creating a REST API Descriptor from a Swagger Document

Service Development Help : Working with REST API Descriptors : Creating a REST API Descriptor from a Swagger Document

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.

The REST API descriptors created from a Swagger document contains REST V 2 resources.

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

Integration Server does not support the following specification parameters in a Swagger document:

tags

security

securityDefinitions

externalDocs

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, do one of the following:

Select...	To generate a REST API descriptor from...
API Portal	APIs present in the API Portal.
CentraSite	A REST resource available in CentraSite.
File/URL	A Swagger document that resides on the file system or on the Internet.

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. 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.

Note:

You cannot edit the elements of the REST API descriptor that you created. You can only edit the service implementation of the services generated.

Note:

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.

Contact Support | Community | Feedback