allow examples to be provided for each property in a typedef

[mmcfarland-novetta]

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.

[kevinccbsg]

Hi @mmcfarland-novetta,

I think you could try to use our example's definitions. You can check more info here, and this example.

As you will see if you run the example you have the option to select the different payloads you define.

We are having some problems with the preview as it renders as a string but if you switch between the different examples it shows properly. You can see more info in this issue #132. However, this should be fixed in the release v1.3.2 (current one) or in a future v1.3.3 release 👍

I think these examples will solve your issue. Please let us know if this is enough 👍

[mmcfarland-novetta]

Please correct me if I'm wrong, but currently the example values can only be provided at the endpoint level, right?

I'm suggesting you also allow example values to be provided at the typedef level. If a number of endpoints in an API can receive/produce a Song object, this would be handy to simplify the documentation.

An example, borrowing a format from another similar library:

/**
 * A song
 * @typedef {object} Song
 * @property {string} title.required - The title - eg: Bury the Light
 * @property {string} artist - The artist - eg: Casey Edwards ft. Victor Borba
 * @property {number} year - The year -  eg: 2020
 */

[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.

[paulish]

Also it is not possible to add example values for the /GET parameters

[lachieh]

Something to consider in future is compatibility with apiDoc

[Ilchuk-Mihail]

Also, looked for that possibility. It's very useful in order to have possibility to reuse examples.

For example, if a few endpoints having same response it would be great if we could describe response example once and reuse them.

[paulish]

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