Data from an OpenAPI Document

Info Component

This topic provides the mapping of data for the Info component of the adapter definition document, generated using an OpenAPI file.

Property in OpenAPI Document	Property in Adapter Definition Document	Filled In During Conversion?	Notes
`"develop:" + info.title`, where any non-alphanumeric character (including spaces) is replaced with a hyphen (`-`), and then truncated to the maximum character length (100) for an ID of the adapter definition document.	`id`	Yes	If the title in the OpenAPI document is `"Basemap styles service"`, the value for the ID field in the adapter definition document is: `"develop:basemap-styles-service"`.
NA	`type`	No	User-defined value.
`info.title`	`displayName`	Yes	Title mapping.
`info.description`	`description`	Yes	Description mapping.
NA	`version`	Yes	Default value filled in is 1.0.0.
NA	`specVersion`	Yes	Default value filled in is 1.0.
NA	`categories`	No	User-defined value.
`info.title`	`appInfo.name`	Yes	Mapping for the `appInfo` object in the adapter definition document; child objects can be empty.
`info.contact.email`	`appInfo.contactUs`	Yes
`info.description`	`appInfo.description`	Yes
`info.contact.url`	`appInfo.supportURL`	Yes
`externalDocs.url`	`appInfo.documentationUrl`	Yes
NA	`publisherInfo.name`	No	User-defined value.
NA	`publisherInfo.description`	No
NA	`publisherInfo.contactUS`	No
NA	`publisherInfo.supportURL`	No
NA	`publisherInfo.documentationURL`	No
NA	`publisherInfo.releaseNotes`	No

Connection Component

This topic provides the mapping of data for the Connection component of the adapter definition document, generated using an OpenAPI file.

Property in OpenAPI Document	Property in Adapter Definition Document	Filled In During Conversion?	Example or Notes
NA	`connectionProperties[].name`	Yes	Fixed value. Set it to `baseURL`.
NA	`connectionProperties[].type`	Yes	Fixed value: `STRING`.
NA	`connectionProperties[].displayName`	Yes	Fixed value: `Base URL`.
NA	`connectionProperties[].required`	Yes	Fixed value: `true`.
NA	`connectionProperties[].hidden`	Yes	The value is `true` if there is an URI in `openapi.servers`; otherwise, it is `false`.
NA	`connectionProperties[].scope`	Yes	Fixed value: single element array containing `"ACTION"`.
NA	`connectionProperties[].tokenized`	Yes	Fixed value: `false`.
The first URI in openapi.servers	`connectionProperties[].default`	Conditionally	If `openapi.servers` is empty, this field won't be filled in.
`components.securitySchemes`. See Security Scheme Object.	`connectionProperties[].securityPolicies`	Yes	The following security policies are supported: No Auth (if no security policy is provided) Basic Authentication Bearer Token Authentication API Key Implement OAuth 2.0 Resource Owner Password Flow Implement OAuth 2.0 Client Credentials Implement OAuth 2.0 Authorization Code For information on how the security policies are implemented, see Learn About Security Policies for Invoke Connections. During conversion, the Rapid Adapter Builder sets a default value for some fields for which it can infer values (such as, `accessTokenUsage`, `oauth.access.token.uri`, `auth.auth.code.uri`), and it sets those fields as `hidden`. However, you can modify the values in the adapter definition document. Further, the following OpenAPI security schemes are implemented using the API-Key Based Authentication security policy: HTTP Bearer Auth API key auth Here are some additional notes about the implementation and mapping of the above security schemes: If there is only Bearer auth, the `accessTokenUsage` security property is resolved to `"-H Authorization: Bearer ${api-key}”` and is hidden. If there is only API Key auth, the `accessTokenUsage` security property is resolved according to whether it is in the header or query, and then it's hidden. If both Bearer auth and Api Key auth are present, the `accessTokenUsage` property is visible with the name `Access token authentication`. If the API Key auth is in the header, the header field is combined (Example: `"-H api_key: ${access_token} -H Authorization: Bearer ${api-key}”`). As it is visible, you can choose which scheme to use. If the API Key auth is a query parameter, the field is left blank. Regarding the OAuth 2.0 security policies, here are some points to note with respect to OpenAPI documents: OpenAPI lists all scopes available, so this is left blank and visible, and you can set your own scope. Fields such as `oauth.client.id`, `oauth.client.secret`, `username`, `password` are left visible, and you can fill the same. The fields `oauth.access.token.uri` and `oauth.auth.code.uri` exhibit the following behavior: For context, all URIs in an OpenAPI document can be relative, so there is a complex behavior for the resolution of access token URI or authorization code URI. OpenAPI documents have a server URI that can be used to resolve relative URIs within the document. However, there can be multiple server URIs and they can be relative. If a fully qualified URI can be unambigously resolved, it is set as the default value and this security property is hidden. This is true for the following scenarios: Either the provided access or auth URI is absolute, or there is one absolute base-server URI and the relative access or auth URI can be resolved against it. If a fully qualified URI cannot be determined for access or authorization, the security property is set to visible with no default value that you can fill in. This is true for the following scenarios: Either the server is relative (to the URI where the OpenAPI document is hosted), or there are multiple servers, or the server invalid, or the access or auth URI is invalid.
NA	`securityPolicies[].type`	Yes	Fixed value: managed

Actions Component

This topic provides the mapping of data for the Actions component of the adapter definition document, generated using an OpenAPI file.

One OperationObject from an OpenAPI document is mapped to one action in the adapter definition document. For information on operation objects, see Operation Object.

The following example illustrates how an operation object in an OpenAPI document is converted to an action in an adapter definition document:

The operation-object data in an OpenAPI document: A GET operation to the object path "/webmaps/arcgis/imagery"
The corresponding action in an adapter definition document: webmapsArcgisImageryGetAction

Other action properties are mapped as follows:

Property in OpenAPI Document	Property in Adapter Definition Document	Filled In During Conversion?	Example or Notes
`OperationObject.summary` or `OperationObject.operationId`	`displayName`	Yes	If the summary isn't present, the operation ID is used as a fallback.
`OperationObject.description`	`description`	Yes	NA
NA	`execute`	Yes	Fixed value: `flow:generalActionFlow`.
NA	`input`	No	Not necessary as an action can contain a reference to the OpenAPI path that maps to the action. From this reference, the input and output schema are derived. Example: `"$refOpenapi": "POST:/pet"` However, actions that are not using OpenAPI can live alongside actions that use OpenAPI.
NA	`output`	No	Not necessary as an action can contain a reference to the OpenAPI path that maps to the action. From this reference, the input and output schema are derived. Example: `"$refOpenapi": "POST:/pet"` However, actions that are not using OpenAPI can live alongside actions that use OpenAPI.
`HTTPMethod:pathName`	`$refOpenapi`	Yes	Example: `GET:/styles/arcgis/imagery`
`servers[0]+pathName`	`configuration[0].default` (path configuration field)	Yes	Every field (except `default`) is fixed. { "name": "path", "type": "TEXT_BOX", "displayName": "Path", "required": true, "readOnly": true, "hidden": true, "default": "/pet" }
`servers[1]+methodName`	`configuration[1].default` (method configuration field)	Yes	Every field (except `default`) is fixed. { "name": "method", "type": "TEXT_BOX", "displayName": "Method", "required": true, "readOnly": true, "hidden": true, "default": "POST" }

Flows Component

This topic provides information for the Flows component of the adapter definition document, generated using an OpenAPI file.

During OpenAPI conversion, no information from an OpenAPI document is added to the Flows section of an adapter definition document. However, after conversion, the following default/generic flow is present in the adapter definition document.

"flows": {
    "generalActionFlow": {
        "id": "generalActionFlow",
        "version": "0.1",
        "start": "startState",
        "specVersion": "0.8",
        "functions": [
            {
                "name": "generalRestFunc",
                "operation": "connectivity::rest",
                "type": "custom"
            }
        ],
        "states": [
            {
                "actions": [
                    {
                        "name": "generalActionFlow",
                        "functionRef": {
                            "refName": "generalRestFunc",
                            "arguments": {
                                "uri": "${ .connectionProperties.baseURL + .configuration.path }",
                                "method": "${ .configuration.method }",
                                "parameters": "${ .input.parameters }",
                                "body": "${ .input.body }"
                            }
                        },
                        "actionDataFilter": {
                            "results": "${ { body: .body, headers: .headers } }",
                            "toStateData": "${ .output }"
                        }
                    }
                ],
                "name": "startState",
                "type": "operation",
                "end": true
            }
        ]
    }
}

Schemas Component

This topic provides information for the Schemas component of the adapter definition document, generated using an OpenAPI file.

As the adapter definition document references the OpenAPI schema ($refOpenAPI), no schemas are generated.

You can identify if an adapter definition document is driven by OpenAPI using the following characteristics:

The presence of "$refOpenapi" in some actions.
The parameter info.settings.supportsRegeneration set to true.