DevOps Edition for Continuous Integration 10.5 | Service Development Help | Working with REST API Descriptors | About 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 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. For example,
Consider the following combination of alternative security schemes:
security: # Basic Auth OR OAuth
- Basic Auth
- OAuth
In this case, Integration Server considers all the supported schemes. Here, it is both Basic Auth and OAuth.
Consider the following combination of must have security schemes:
security: # Basic Auth AND OAuth
- Basic Auth
OAuth
In this case, Integration Server considers only the first supported security scheme. Here, it is Basic Auth.
Consider the following combinations of both alternative and must have security schemes:
security: # (unsupportedScheme AND OAuth) OR (Basic Auth AND OAuth)
- unsupportedScheme
OAuth
- Basic Auth
OAuth
In this case, Integration Server considers both the combinations with the first supported security scheme. Here, these are OAuth and Basic Auth.
* 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 dialog box, 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 Select the Source Type dialog box, select Provider.
6. Select Swagger Document as the RAD source and click Next.
7. In the Select the Swagger Document Location dialog box, 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:
*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.
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.
8. 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.
Notes:
*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 .
Copyright © 2017-2019 | Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.