feat: support array examples at arbitrary levels #853

ad-world · 2024-07-29T17:38:24Z

This PR removes support for the @arrayExample jsdoc, and extends the functionality of the @example tag so that it can be used with arrays to show array example and non-array examples as well.

This is how to use the new functionality.

Case 1.
Want to show an example of an item within the array

/**
@example exampleItem
*/
field: t.array(t.string)

This will render as this:

{
    type: 'array',
    items: {
        type: 'string',
        example: 'exampleItem'
    }
}

Case 2. Want to render an array example

/**
@example ["exampleItem1", "exampleItem2"]
*/
field: t.array(t.string)

This is how it would render:

{
    type: 'array',
    example: ['exampleItem1', 'exampleItem2']
    items: {
        type: 'string'    
    }
}

Case 3. Want to render an item + array example

/**
@example btc
*/
const coinString = t.string

... 
/** 
@example ["btc", "eth"]
field: t.array(coinString)
*/

This is how it would render:

{
    type: 'array',
    example: ['btc', 'eth']
    items: {
        type: 'string',
        example: 'btc'
    }
}

DX-622

packages/openapi-generator/test/openapi.test.ts

ericcrosson-bitgo

Test cases look good.

What is your plan regarding call-sites that are using arrayExample today?

Please add the missing semicolon that the linter flagged and once we have a solid roll-out plan, this looks good to merge

DX-622

ad-world · 2024-07-29T18:25:17Z

What is your plan regarding call-sites that are using arrayExample today?

First step is to update all @arrayExample's in WPT to just use @example. There are only 2, so it is a trivial task.
Next step is to generate WPT docs locally (with this update and check diffs with current wallet-platform.yaml. Nothing should change.
Next step is to bump openapi-generator in dev-portal (after this is merged), so that the changes are put into effect

ad-world · 2024-07-29T19:05:50Z

https://github.com/BitGo/wallet-platform-types/pull/478 !

ericcrosson-bitgo

Seems fine to not consider this a breaking change since the removed arrayExample tag is undocumented and was recently added -- so adoption is expected to be minimal.

Approving but not merging yet so you can coordinate this with your other PRs

github-actions · 2024-07-29T20:29:57Z