Creating a Provider REST API Descriptor from a Swagger Document
You can create a provider REST API descriptor (RAD) from:
External Swagger document accessible through a URL
A REST API on
API PortalA REST resource/service residing in CentraSite
Keep the following in mind when creating a RAD from a Swagger document:
The Swagger document that you use to create a provider RAD must be based on the Swagger Specification version 2.0.
To create a provider 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 provider RAD.
If the Swagger document does not contain a base path, then
Integration Server adds the namespace of the RAD as the base path after creating the RAD.
Integration Server does not support multi-dimensional arrays (String table) in the input or output signature of a service mapped to the REST V2 resources. If you implement multi-dimensional arrays in service, the REST API response of the service might be invalid.
Integration Server supports the following security schemes from the list of security schemes in the Swagger Specification version 2.0.
Basic Auth OAuth If the Swagger file contains combination of multiple security schemes for the REST resource, then
Integration Server considers the security schemes differently. See
Multiple security schemes for similar concepts.
If the Swagger document does not have a security definition, the REST API is invoked with the authentication mechanisms such as Basic, Digest, or JWT.
To create a provider 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 Provider.
7. Select Swagger Document as the RAD source and click Next.
8. In the Select the Swagger Document Location wizard page, select one of the following to perform the corresponding action in Designer:
Task Selection | 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. |
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. | Select the check box. |
9. Click Finish.
Designer creates the provider RAD. It also creates the associated services (services), definitions (docTypes), and resources (resources) and places them 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:
You cannot edit the elements, the general information in the
General tab, or the MIME type of the RAD that you created. You can only edit the service implementation of the services generated.
Ensure that you 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 RAD to a different location in
Designer, ensure that you move the corresponding folder containing the
services,
docTypes, and
resources folders.