Creating a Provider REST API Descriptor from an OpenAPI Document

Designer 10.7 | webMethods Service Development Help | Working with REST API Descriptors | OpenAPI-Based Provider REST API Descriptors | Creating a Provider REST API Descriptor from an OpenAPI Document

You can create a provider REST API descriptor (RAD) from an OpenAPI document accessible through a URL or file system.

Keep the following in mind when creating a provider RAD from an OpenAPI document:

Ensure that the OpenAPI document that you use to create a provider 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.

If the OpenAPI document contains multiple security authentication mechanisms, then Integration Server handles the authentication mechanisms as mentioned below. For example,

Consider the following combination of logical OR authentication mechanism:

security: # basic OR oauth2
- basic
- oauth2

In this case, Integration Server considers all the supported authentication mechanisms. So, client can send both basic and oauth2.

Consider the following combination of logical AND authentication mechanism:

security: # basic AND bearer
- basic
bearer

In this case, Integration Server considers only the first supported authentication mechanism. So, client can send only basic.

Consider the following combinations of both logical OR and logical AND authentication mechanisms:

security: # (apiKey AND oauth2) OR (basic AND digest)
- apiKey
oauth2
- basic
digest

In this case, Integration Server considers both the combinations with the first supported authentication mechanism. So, client can send oauth2 and basic.

Note:

When an OpenAPI document contains authentication mechanisms that are not supported by Integration Server, then while creating the RAD, Integration Server still generates the assets; however, does not support the authentication mechanisms during runtime.

Integration Server does not support apiKey and openIdConnect authentications and if the OpenAPI document contains operations requiring these authentication mechanism, Integration Server still generates the assets for those operations; however, those operations can be accessed using basic authentication.

To create a provider 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 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, by default Designer selects RAD as Provider and the source type as OpenAPI Document. Click Next.

7. In the Select the OpenAPI Document Location wizard page, select the following to perform the corresponding action in Designer:

Task Selection	Purpose	Course of Action
File/URL	Generate a RAD from an OpenAPI document that resides on the file system or on the Internet.	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://. Provide your username and password to use the OpenAPI document from the website.
Import OpenAPI document based on tags	Groups the operations under a REST V2 resource based on the tags. If you do not select this option, Designer groups the operations by path.	By default, the check box is selected.
Document name prefix	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.	Add a prefix name.

8. Click Finish.

Designer creates the provider RAD based on the OpenAPI document and also creates the associated services (under services folder. For more details, see About Services), JSON document types (under docTypes folder. For more details, see About JSON Document Types), callback services (under callbacks folder. For more details, see About Callbacks), and resources (under resources folder) 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 and other details for the RAD. For more information about the fields in the Properties view, see REST API Descriptor Properties.

Note:

After you create the RAD, you can only edit the server details under the Server tab and service implementation of the callback and flow services.

You must not rename or delete the services, docTypes, callbacks, and resources folders, its subfolders, or the parent folder containing them all; otherwise Designer behaves unexpectedly when you refresh the RAD. Also, when you move or copy the RAD to a different location in Designer, move or copy the associated folders as well.

If there is any change in the OpenAPI document and you want to refresh the generated assets, you can refresh the RAD in Designer. For more information, see Refreshing a REST API Descriptor .