Description
Since the spec discourages the use of example in favor of examples on schema objects, it would be nice if we didn't lose the @example JSDoc when the user follows that recommendation.
Proposal
I suggest one of two alternatives:
Approach 1 - use the first example
Since one might reasonably expect that examples will often only have one element, we can check if schemaObject.examples is an array (and not a Map of Example Objects, as it would be for other components) in src/transform/components-object.ts and copy the first element of it to example, if no example property is already present. This will preserve the current functionality as folks migrate from the use of example to examples without interfering with any other uses of examples.
Note that you can technically do this with the transform function, but it relies on modifying the schemaObject that is passed into the transform function by reference, which one has no reason to expect will continue to work. Personally, I'd consider that just a workaround.
Approach 2 - multiple @example tags
Since JSDoc allows multiple @example tags, we can check if schemaObject.examples is an array in src/lib/ts.ts, and if it is, output each element in the array as a separate @example tag. Since other components of the OpenAPI definition use a Map of Example Objects rather than an array, we should only affect JSON Schema output, and will include all examples, which might be more in line with what a user would expect.
Extra
Description
Since the spec discourages the use of
examplein favor ofexampleson schema objects, it would be nice if we didn't lose the@exampleJSDoc when the user follows that recommendation.Proposal
I suggest one of two alternatives:
Approach 1 - use the first example
Since one might reasonably expect that
exampleswill often only have one element, we can check ifschemaObject.examplesis an array (and not a Map of Example Objects, as it would be for other components) in src/transform/components-object.ts and copy the first element of it toexample, if noexampleproperty is already present. This will preserve the current functionality as folks migrate from the use ofexampletoexampleswithout interfering with any other uses ofexamples.Note that you can technically do this with the
transformfunction, but it relies on modifying theschemaObjectthat is passed into the transform function by reference, which one has no reason to expect will continue to work. Personally, I'd consider that just a workaround.Approach 2 - multiple @example tags
Since JSDoc allows multiple @example tags, we can check if
schemaObject.examplesis an array in src/lib/ts.ts, and if it is, output each element in the array as a separate@exampletag. Since other components of the OpenAPI definition use a Map of Example Objects rather than an array, we should only affect JSON Schema output, and will include allexamples, which might be more in line with what a user would expect.Extra