API console refinements

[BK01]

Refinements based on initial UAT of API Console in cad.data using OpenAPI 3.x specs

[BK01]

Issue on hold until a new release of swagger-ui is available. Currently the following is not available in swagger-ui 3.2. May be available in October.

• Parameter dropdown lists
  OAS 3.0 Support Backlog swagger-api/swagger-ui#3641

• Authorize
  Has the Authorize button been implemented for OAS3.0? It does not display. swagger-api/swagger-ui#3665

[BK01]

Next steps:

Change ticket - branch director
Migrate cat.data API console to PROD (ckan ext 1.2), use existing OpenAPI 2 specs.

[BK01]

@banders to test new release of swagger-ui

[banders]

@BK01 @ll911 I have updated my local version of the API Console to use the latest release of swagger-ui (3.3.1). This version still doesn't support parameter drop-down lists or authorizations (i.e. Get API Key) for OAS 3 spec files. I can push the latest version to github so you can install in CKAN dlv, but I don't see much point.

Probably best to continue to monitor the swagger-ui releases for updates before we upgrade our API console...

[ll911]

I think we can hold it off till the version we need.

[BK01]

@banders to review latest release to determine if latest version of swagger-ui (3.3.2) meets our requirements.

[banders]

@BK01 @ll911 There is an even newer version of swagger-ui than 3.3.2. 3.4.0 is the latest.

I have tested 3.4.0 and found some improvements, but also a new bug. Here's a summary:

• Param drop-down lists now working for OAS3
• Authorize (i.e. "Get API Key") now working for OAS3
• Try-it-out Execute button no longer working for OAS3

I posted this bug report with the swagger-ui community to report the Try-it-out bug. We can't use the latest version until the bug is fixed.

[BK01]

@banders To evaluate version 3.4.1

[banders]

@BK01 swagger-ui 3.4.2 seems to fix our main concerns over support for OAS3. I have merged this version of swagger-ui into the API Console. Can we try redeploying the API Console in delivery for additional testing?

[BK01]

@Darv72 Can we try redeploying the API console in DLV.

[Darv72]

@BK01 The console should now be deployed in DLV. Let me know if there is anything further.

[BK01]

@banders @Darv72 New API console is deployed in DLV and ready for testing with OAS3. Initial tests with the combined geocoder spec are looking good.

[BK01]

@BK01 DataBC complete UAT for all OAS3 specs in cad.data this week.

[BK01]

Copy request URL and open request URL buttons to be implemented in new version of console.

[banders]

@BK01 @Darv72 I have ported the "Copy Request URL" and "Open Request URL" functionality to the new version of swagger-ui. The new code has been merged into ckanext-openapiviewer. There's a slight change to the behaviour:

• The "Copy Request URL" button is gone. Now, just click on the request URL itself and it is automatically copied. We still have a button for "Open Request URL". This is consistent with how stock swagger-ui handles copy-to-clipboard for the CURL command.

Note that "Open Request URL" will always opens the link in a new tab, but will give an API key error for gated APIs in which the API key is not part of the request URL. (e.g when the key is in the header). I think this is reasonable behaviour, but let me know if you think we should handle the situation differently.

[BK01]

Thank you. DataBC will deploy the new code to cad.data for UAT.

[BK01]

Successful UAT in cad.data