Add support for JSON Schema `examples` keyword on Schema objects

[cmlee-accelins]

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

• I’m willing to open a PR (see CONTRIBUTING.md)

[cmlee-accelins]

If there are no objections, I will put up a PR for approach 2.