Creating a Consumer REST API Descriptor from an OpenAPI Document
You can create a consumer REST API Descriptor (RAD) from an OpenAPI document accessible through a URL or file system.
Ensure that the OpenAPI document that you use to create a consumer RAD is valid and based on the OpenAPI Specification version 3.0.x.
Integration Server supports the following authentication mechanisms from the OpenAPI Specification version 3.0.x:
HTTP authentications:
Basic,
Bearer, and
Digest.
OAuth 2.0 flows:
Authorization Code,
Implicit,
Resource Owner Password Credentials or
Password, and
Client Credentials.
OpenID connect discovery
API key-based
To create a consumer REST API descriptor from an OpenAPI 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 create the RAD.
3. In the Element 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, click OpenAPI 3.x as the specification version of the source. Click Next.
6. In the Select the Source Type wizard page, select Consumer, and click Next.
7. In the Select the OpenAPI Document Location wizard page, select the following to perform the corresponding action in Designer:
File/URL: Do one of the following:
Click
Browse to navigate to and select an OpenAPI document on your local file system.
Enter the URL for the OpenAPI document. The URL should begin with http:// or https://.
Note:
If the website needs to authorize your access to the OpenAPI document, provide your user credentials.
Document name prefix: Add a prefix name.
Designer uses this as prefix name while creating the JSON document types and variables for anonymous schemas. If you do not add a prefix, by default Designer adds _untitled as prefix. The prefix name must not be the same as the schema name or the property name present in the OpenAPI document.
8. To choose the REST operations from the selected OpenAPI document, click Next and select one or more REST operations. Based on your selection, Integration Server generates the connector services corresponding to the REST operations. Otherwise, click Finish.
Designer creates a read-only consumer RAD. It also creates the associated REST connector services (under connectors folder), callback services (under callbacks folder), and document types (under docTypes folder) and places these folders under a folder that has the same name as the RAD appended with an underscore (_).
The generated RAD contains the following components:
Servers tab: Highlights the API servers hosting the REST services. For more information, see
Working with Servers.
Operations tab: Highlights the REST operations supported by the OpenAPI document. For more information, see
Working with Operations.
Schemas tab: Highlights the schemas and JSON document types supported by the OpenAPI document. For more information, see
Working with Schemas.
Security tab: Highlights the security definitions supported by the OpenAPI document. For more information, see
Working the Security.
Tags tab: Highlights all the tags supported by the OpenAPI document. For more information, see
Working the Tags.
The
Properties view displays the source URL and source URI value for the RAD. For more information about the fields in the
Properties view, see
REST API Descriptor Properties.
Note:
Do not rename or delete the
docTypes folder,
callbacks folder, or
connectors folder and subfolders, or the parent folder. Also, if you move the RAD to a different location in
Designer, move the associated folders as well.
Ensure that you do not modify the input or output signatures of the generated connector services; otherwise the connector services might not work as expected.
When you run a connector service corresponding to a REST operation and does not provide any value for an input field,
Integration Server passes an empty string for that field.