1. Using the Oracle Utilities Adapter with Oracle Integration 3
  2. Troubleshoot the Oracle Utilities Adapter
  3. Using the Swagger 2.0 REST Catalog with Oracle Utilities Adapter Version 24.04.0 or Higher

Using the Swagger 2.0 REST Catalog with Oracle Utilities Adapter Version 24.04.0 or Higher

If you use the Swagger 2.0 REST catalog in a connection with Oracle Utilities Adapter version 24.04.0 or higher, the following error is displayed when you click Test for the connection. 

Swagger 2.0 is no longer supported in Utilities Adapter. Please use openAPI 3.x REST catalog. 
Please check Utilities Adapter documentation for more information.

If there is any existing integration using the Swagger 2.0 REST catalog, runtime won't be impacted. However, if you try to edit the design-time connection, retest the connection, refresh the metadata, refresh the artifacts, or reactivate, the integration fails. You must update the catalog to use the OpenAPI 3.x definition.

Note:

All Utilities Integration Accelerators on Oracle Integration 3 support OpenAPI 3.x catalog definitions. All non-OUAF (NMS) application catalogs are already on OpenAPI 3.x. For custom integrations, verify first if you are already using the OpenAPI 3.x catalog and your mappings are OpenAPI 3.x-compatible.

Differences Between the REST Swagger 2.0 Catalog and OpenAPI 3.x Catalog

To understand the difference between the two specifications:
  1. Open Postman and GET the REST catalog response by providing valid credentials.


    The image shows the GET operation, the API, and Send button at the top. Below this are the Params, Authorization, Headers, Body, Pre-request Script, Tests, and Settings tabs. Below this is the Type list, which shows Basic Auth selected. To the right are the Username and Password fields and Show Password check box. Below this are tabs for Body, Cookies, Headers, and Test Results. Below this are tabs for Pretty, Raw, Preview, and Visualize. JSON is selected from a list. Below this is each row of the code.

  2. In the catalog response, check for any business service openAPIUrl field with the following format.
    <openAPIUrl>https://<hostname>:<port>/ouaf/rest/ouaf/openapi/v2/<servicename></openAPIUrl>
    • If openAPIUrl contains /v2 in the URL, it's a Swagger 2.0 catalog. You can also access openAPIUrl from Postman or the Swagger editor using the GET openAPIUrl response. If the response contains swagger : 2.0, it's a Swagger 2.0 catalog.


      The image shows the GET operation, the API, and Send button at the top. Below this are the Params, Authorization, Headers, Body, Pre-request Script, Tests, and Settings tabs. Below this is the Type list, which shows Basic Auth selected. To the right are the Username and Password fields and Show Password check box. Below this are tabs for Body, Cookies, Headers, and Test Results. Below this are tabs for Pretty, Raw, Preview, and Visualize. JSON is selected from a list. Below this is each row of the code.

    • If the openAPIUrl field doesn't contain /v2 in the URL, it's an OpenAPI 3.x catalog. You can also access openAPIUrl from Postman or the Swagger editor using the GET openAPIUrl response. If the response contains openapi : 3.x.x, it's an OpenAPI 3.x catalog.


      The image shows the GET operation, the API, and Send button at the top. Below this are the Params, Authorization, Headers, Body, Pre-request Script, Tests, and Settings tabs. Below this is the Type list, which shows Basic Auth selected. To the right are the Username and Password fields and Show Password check box. Below this are tabs for Body, Cookies, Headers, and Test Results. Below this are tabs for Pretty, Raw, Preview, and Visualize. JSON is selected from a list. Below this is each row of the code.

Replace REST Swagger 2.0 with the OpenAPI 3.x Catalog in an Integration

If your integration is using the REST Swagger 2.0 catalog in a connection, replace it with the OpenAPI 3.x catalog of the application. The catalog URL configured on the Connections page does not have any difference. Only the openAPIUrl of the specification for the inbound/outbound service in the catalog is different. The mappings in the design-time mapper are impacted after this change if the integration is edited.

If you are already using the OpenAPI 3.x catalog specification, verify it by opening the mapper for the corresponding Oracle Utilities Adapter. Verify if the root node begins with components.schemas.
  • If it does, your catalog is an OpenAPI 3.x-supported catalog and the integration should work as is.
  • If it's not, your mappings are old and using the Swagger 2.0 specification, which needs to be updated.

Otherwise, no change is needed and your custom integration should work without issues. If the mapper is using the Swagger 2.0 specification, it is recommended that you follow the knowledge article Steps To Fix Mapper Issue With Swagger2.0 To Open API 3.x to redo the mappings because the old mapping does not work in Oracle Integration 3.