microsoft / microsoft/typespec

[Bug]: OAS Emitted doesn't include @example decorator value in Operation parameters

Open
#7,339 2 comments 0 reactions 0 assignees View on GitHub
bug emitter:openapi3 triaged:core
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

### Describe the bug

when emitting OAS for an operation defined like the below, it'll emit/include the @doc value on the id parameter, but the @example value is NOT emitted
```
@patch op update(
@example(1) // This doesn't end up in the generated OAS
@doc("this work...")
@path id: int32;
@body order: Order;
): { ... }
```

The allowed targets for @path is a ModelProperty, which must mean that the 'id' path parameter in my example is something of type ModelProperty

@example also has ModelProperty as allowed target, so from that perspective I would expect the example value to appear in the emitted OAS

If I manually modify the emitted OAS and add an example property on the id parameter, I get no validation errors and the example shows up in the Swagger Editor, indicating that adding examples to operation parameters is supported in OAS

### Reproduction

Paste the sample above in a TPS file and emit OAS

### 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.