Upgrade API Console Viewer

[BK01]

Upgrade the swagger-ui version which is embedded in CKAN API Console. The API Console currently uses swagger-ui version is 2.x but should be upgraded to 3.x.

As part of the upgrade, also attempt to address usability issues arising from swagger-ui being enclosed within a BCDC iframe. Display of swagger-ui within an iframe is problematic because:

• the iframe is currently a fixed height and width so space is restricted
• the default skin for swagger-ui requires lots of vertical scrolling, which isn't ideal within the limited extents of the iframe
• nesting of scrollable areas within the iframe causes frustration when using a mouse scroll wheel

Consider the following as possible approaches to improving the usability issues with swagger-ui in the iframe:

• Keep the standard swagger-ui skin, but embed it in BCDC without an iframe. This wasn't practical with swagger-ui 2.x, but may be possible if the new swagger-ui doesn't have style conflicts with BCDC/Bootstrap CSS
• Keep the standard swagger-ui skin, keep the iframe in BCDC, but check if CKAN can resize the iframe to the full length of its content so we reduce problems of nested scrollable areas. This is actually the default behaviour for CKAN resource view plugins, but there was a graphics glitch due to the CSS used by swagger-ui 2.x. It may be that the graphics glitch is no longer an issue with the CSS used by swagger-ui 3.x.
• Re-skin swagger-ui to utilize a more space efficient layout that relies less on scrolling. Perhaps a layout more like the one used for this project. Swagger-ui 3.x apparently has more extension points than previous versions, so perhaps re-skinning without core code changes is practical.
• Other ideas??

[banders]

I have updated the API Console to use swagger-ui 3. An example is available here.

What you see in the example is a completely stock version of swagger-ui 3, although I have made a small change to how it is embedded in the CKAN plugin so that the iframe now stretches vertically to fit the swagger-ui contents.

You'll notice that swagger-ui 3 undoes some of the customizations that we previously applied to swagger-ui 2. For example, the bright green header is back, and the "Copy Request URL" button is gone. On these two specific issues we have already ported the customizations to swagger-ui 3 and I will include them in the next patch.

We investigated the option of re-skinning swagger-ui 3 with a more space-efficient layout. Although the swagger-ui github readme suggests that version 3 is much more customizable, there is not yet documentation on the swagger-ui extension points. I suggest we don't apply a re-skin until there is more documentation.

@bk01 @ll911 what are your thoughts about the swagger-ui 3 example in the link at the top of this comment? Does the change to vertically extend the iframe help? Are there other look & feel priorities to focus on as part of the upgrade to swagger-ui 3?

[ll911]

@banders thx brock, the ui issue still related to the fixed iframe, feedback from users that too much white spaces on both side. any idea on custom jinja2 template to modify for the extension?

[banders]

@ll911 I will loook into making the template wider...

[banders]

@ll911 @BK01 The template for resource views is nested within other templates. The maximum width of a resource view is dictated by HTML and CSS from at least one of the outer templates. The relevant outer template is used by most (all?) of the pages within BCBC. So we can widen the maximum width available for the API Console resource view, but that would essentially widen the central content area on most of the BCDC pages. Is that what you have in mind? If so, it is probably something that should be modified in the ckanext-bcgov extension.

[ll911]

@banders ideally, it would be great not have the iframe, without change existing package view can check if following feasible, 1, https://github.com/ckan/ckanext-pages and http://swagger.io/docs/swagger-tools/#customization-36 is this approach not limited in the iframe? 2, place api console like this in the full modal window or new tab?

[banders]

I have created a new button "Open in new tab" on the resource view. While the resource view within BCDC is still limited by the width of the page template, users now have the option to view a full-page version in a new tab.

Note: the "Open in new tab" button affects all resource views, not just the API Console. So, for example, json, geojson, plaintext and PDF resources will now also have the "Open in new tab" button.

[banders]

The discussion in this issue is also relevant to issue 41. This issue has come to encapsulate issue 41.

[BK01]

@BK01 Swaggerui 3 vs. 2 review/qa + feedback

[banders]

@ll911 @BK01 The "Open in new tab" button is intended to be a work around to the problem of improving the presentation of swagger-ui within the BCDC application. Ideally we will be able to re-skin swagger-ui with a look & feel that is more suitable for the limited screen real estate within the BCDC application template.

Although swagger-ui 3 was apparently designed to be extensible, there don't seem to be any docs on the extension points yet. This makes re-skinning impractical right now. I have posted a request to this swagger-ui issue for some documentation on the swagger-ui 3 extension points.

[BK01]

dataproxy issue resolved

[BK01]

@BK01 to investigate presence and default viewing of 'text' tab in API console. Present in DLV, not in PROD. Likely a BCDC configuration issue.

[BK01]

The 'result content type' drop down list appears to update the Curl, but not the request URL. Furthermore, the list of formats appears to be listed differently from the 'OutputFormat' drop down list shown for the Geocoder.

[banders]

@BK01 The "Content Type" drop-down list that appears in the "Responses" section is created by swagger-ui to match the "Produces" section of API spec. The OpenAPI 3 specification says the "Produces" section must be "A list of MIME types the operation can produce."

The issue here is that swagger-ui makes some assumptions about the "Produces" list:

• Swagger-ui assumes that API uses the "Accept" HTTP header to control the output format. It passes the selected content type in the "Accept" header.
• Swagger-ui is unaware of the fact that some APIs instead use a query string parameter (such as outputFormat=...) to control the output format.
• If the API spec doesn't include a "Produces" section, swagger-ui assumes "application/json".

I think that swagger-ui is making bad assumptions here, and we should create an issue in their project to request a change.

Thoughts?

[BK01]

@banders to remove content type drop down list from our fork of swagger-ui, and create an issue for review by the community.

[banders]

I created a new issue for the swagger-ui community describing the problem with the response "Content Type" drop-down list.

[BK01]

@BK01 to repeat UAT when next delivery is received.

[BK01]

Next Step: Migrate GWA to PROD, then update the API console to point to GWA in PROD

[BK01]

@banders GWA has now been migrated to PROD. Next steps - point API console to GWA PROD.

BCDC 1.6.6 will also need to be migrated to PROD, although the BCDC 1.6.6 migration will need to wait until after the wildfire state of emergency is over.

[BK01]

Note: The latest API console is in cat.data and pointing to GWA in PROD