microsoft / microsoft/typespec

[Bug]: multiple @example on an object or property should warn when using OpenAPI emitter

Open
#4,511 3 comments 1 reaction 1 assignee Claimed by @chrisradek View on GitHub
bug design:needed emitter:openapi3 triaged:core
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

### Describe the bug

In OpenAPI, parameters, requests, and response all support `examples`. However, objects and properties only support (a single) `example`.

Trying to use `@example` twice in such a case should result in a compilation error., or at least a visible warning.

### Reproduction

[Playground link](https://typespec.io/playground?c=QGV4YW1wbGUoI3tCYXI6ICJBIn0pCtEWQsQWbW9kZWwgRm9vCnsKICDJJCJBIinNEELFEMU5c3RyaW5nOwp9&e=%40typespec%2Fopenapi3&options=%7B%7D). Note that when multiple `example`s are specified, the last is silently chosen.

### Checklist

- [X] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [X] Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
- [X] Check that this is a concrete bug. For Q&A open a [GitHub Discussion](https://github.com/Microsoft/typespec/discussions).
- [X] The provided reproduction is a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) of the bug.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.