[openapi3] add support for parameter examples via @opExample

[chrisradek]

Fixes #3873

This PR adds support for generating parameter examples in openapi3.

Notes:
From the OpenAPI spec (https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-for-use-with-schema):

When example or examples are provided in conjunction with the schema field, the example SHOULD match the specified schema and follow the prescribed serialization strategy for the parameter.

The parameter-level examples are meant to be serialized as they would appear over the wire. This means in some cases, they conflict with the parameter schema. For example, when a header parameter is an array.

The OpenAPI spec provides a table that shows what an example should look like for any given parameter style:
https://spec.openapis.org/oas/v3.0.4.html#style-examples

Link to inconclusive discussion on the correct way to represent example in OpenAPI 3 OAI/OpenAPI-Specification#4622

[github-actions]

All changed packages have been documented.

• ✅ @typespec/openapi3

Show changes

@typespec/openapi3 - feature ✏️

Adds support for parameter examples via @opExample via the experimental-parameter-examples option.

[azure-sdk]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

[timotheeguerin]

For reference link to inconclusive discussion on what is the correct way OAI/OpenAPI-Specification#4622

[timotheeguerin]

This looks good, lets maybe make sure everyone is onboard with having it has this experimental flag vs just naming it parameter-examples

[timotheeguerin]

Lets just do that and we can change the property later when we have more info