allow examples to be provided for each property in a typedef

When I’m defining a schema consisting of types containing properties, it would be handy to specify the example values which should appear in the request & response examples that reference that type.

Given a type:

/**
 * A song
 * @typedef {object} Song
 * @property {string} title.required - The title
 * @property {string} artist - The artist
 * @property {number} year - The year - double
 */

I’d like some way (if it doesn’t already exist) to specify example values of “My Song”, “Artist X”, and “2021” for the 3 properties.

I may have an API GET /api/songs would automatically have a sample response like

[
  {
    "song": "My Song",
    "artist": "Artist X",
    "year": 2021,
  }
]

instead of

[
  {
    "song": "string",
    "artist": "string",
    "year": 0,
  }
]

Other APIs GET /api/song/:name and PUT /api/song could each benefit from those example values without duplicating those sample values in @example request and @example response blocks.

Eventually, I’d like to have types derived from Song using anyOf which would inherit those sample values for each property.

[paulish]

With release 1.6.7 you can do it this way: @param {string} page.query.required - Page number - json:{"minimum": 0, "example":2}

[kevinccbsg]

Hi @mmcfarland-novetta,

Yes, you are right 🤔 we still don’t have support for that. I will mark this as an enhancement to take a look at in future releases.