feat: support array examples at arbitrary levels

BitGo / api-ts

Type- and runtime- safe TypeScript APIs

https://bitgo.github.io/api-ts

Other

15 stars 21 forks source link

feat: support array examples at arbitrary levels #853

Closed ad-world closed 1 month ago

ad-world commented 1 month ago

DX-622

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'
    }
}

ad-world commented 1 month ago

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 commented 1 month ago

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