feat: allow for single example

[cedvdb]

resolves #1619

Allows for a single @example in comment tags.

Previously the parser assumes that there might be multiple such tag in comments and add it to an array of example, transforming the original @example into example. If there is only one of such tag, this make it so it return example instead.

This is important because examples is not valid in openapi for example.

[cedvdb]

@domoritz tests have been changed,

I modified the current test as there is already one for multiple examples under it. I think now it covers both scenarios.

Current next branch (without these changes) has tests failing.

[domoritz]

Is this actually better? The old format is more predictable and easier to process since it's consistent.

Can you send a link to json schema spec about this tag?

[cedvdb]

Not sure, Examples does not pass validation under openapi spec, while example does.

Here is the spec on examples: https://json-schema.org/draft/2020-12/json-schema-validation.html#name-examples it says nothing about example

There are instances of example being used in open api specs https://swagger.io/specification/ which is not a 1:1 with json schema.

There is a flag: discriminatorType: 'open-api' in the config that could be used ?

[domoritz]

Hmm, then I would say this is an issue to raise with openapi and swagger. I don't really want to diverge from JSON schema.

I was somewhat reluctant to add the discriminatorType flag and would not like to support too many flags.

[cedvdb]

Makes sense.

would not like to support too many flags.

the open api flag seems to be already there

You might close this PR if you wish, I don't think there is anymore to be done here.

[domoritz]

How about we add one flag for openapi support and use that for all openapi related features?