Try Example button

[BK01]

Write a custom extension for swagger-ui to add a 'Try a Sample' button to the API console.

The extension will submit a request to the respective API using the example provided in the OpenAPI spec.

Next Step:

Brock to confirm feasibility / provide an estimate

[banders]

@BK01 @ll911 I think this task is possible, but I can't be certain until digging deeper into the code.

I expect that if we encounter any major obstacles they will appear early in the development work. I propose that we could alert you of any such obstacles if they arise. If no major obstacles, I'd estimate about 2 days effort.

Let me know if you'd like us proceed.

[banders]

@BK01 Looking into the swagger-ui source code a bit more, Sean expects no major obstacles to adding a "Try a Sample" button if we specify examples with our spec files by putting the "example" directly into the "parameter".

If we also want to support examples specified using references (such as $ref: '#/components/examples/zip-example') then we'd need to make some supporting updates deeper within swagger-ui that would complicate the task.

I suggest we start by supporting examples directly within parameters and leave out support for referenced parameters for now.

[BK01]

New patch to be implemented in DLV this week for review.

[banders]

@BK01 @ll911 I have merged the new Try Example code into ckanext-openapiviewer. I also merged in the newest swagger-ui (v3.3.1). PR is here.

Known Limitations:

• The Try Example button only works with OAS 3 files. (OAS 2 doesn't support parameters examples.) I have added examples to the OAS 3 version of bcgnws.json. We can use that as a test case.

• The current version of swagger-ui (3.3.1) still lacks full support for Try it out and Execute. With Execute not fully working, Try Example currently only populates the form with example values, but the query cannot actually be executed yet. I'll continue to monitor the swagger-ui releases for a patch.

[BK01]

Already implemented. Waiting on new version of swagger-ui that meets requirements. Will be active if swagger-ui 3.4.1 meets requirements.

[BK01]

To test in cad.data with BCGNWS spec (OAS3).

[banders]

Recall we have been awaiting a version of swagger-ui that correctly supports "Try it out" and a couple other things that were previously unsupported for OAS3. Looks like the latest swagger-ui now supports all of the prerequisites, so we will update our code for "Try example" to work with the latest release.

@BK01 We Should have a version of "Try example" ready to test later this week.

[banders]

@BK01 When we first implemented the preliminary "Try Example" functionality, swagger-ui didn't support any functionality around parameter examples. The latest swagger-ui does have some out-of-the-box functionality for displaying examples via the normal "Try it out" form. Here's how swagger-ui now works out-of-the box:

For each form field the value is set as follows:

1: If there is already a value in the field (ie, if the user hits cancel and then "Try it out" again, it won't re-update the value) 2: If there is an "example" key/value on the parameter, use that 3: If there is a "default" key/value pair on the parameter, use that 4: If it is required, and is an enum, use the first enum in the set

This isn't the same as a "Try Example" button, but it may make "Try Example" unnecessary, or perhaps a bit confusing. What do you think? Should we just stick with the out-of-the-box functionality?

[BK01]

Deploy latest viewer (see GitHub) in cad.data and test 'try it out' button with new capabilities using OAS 3 specs (bcgnws example). Consider reviewing / adding examples to other specs where applicable.

[BK01]

To test when latest release of swagger-ui is deployed.

[BK01]

To investigate why example value not populating API console. Tested in petstore and cad.data.

[banders]

@BK01 There was a problem with how parameter examples were defined in the bcgnws spec. I have fixed this. The corrected version is here:

https://raw.githubusercontent.com/banders/api-specs/upgrade-to-openapi3/bcgnws/bcgnws.json

I have confirmed that examples are correctly showing in the "Try it out" forms.

[BK01]

Successful UAT completed in cad.data with BCGNWS console.