Designer 10.7 | webMethods Service Development Help | Working with REST API Descriptors | Swagger-Based Provider REST API Descriptors | Creating a Provider REST API Descriptor from a Swagger Document
 
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 Portal
*A 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.
*If there is any change in the RAD, you can refresh the RAD in Designer. For more information, see Refreshing a REST API Descriptor .