microsoft / microsoft/typespec
Provide mechanism to use example objects
- Dominant language
- Java
- Stars
- 5.9k
- Forks
- 394
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 104
Description
### Clear and concise description of the problem
When defining complex models with full fledged examples, it would be helpful to be able to define an example object, and then reference it both as an object and as parts to fill out complete OpenAPI examples.
Example:
```tsp
const exampleWidget = #{
id: "1",
weight: 2,
color: "red",
};
@example(exampleWidget)
model Widget {
@visibility("read", "update")
@path
@example(exampleWidget.id)
id: string;
@example(exampleWidget.weight)
weight: int32;
@example(exampleWidget.color)
color: "red" | "blue";
}
```
Alternatively, it would be fantastic if the model example would automatically add the doc for all the members without requiring duplicate @example tags. In most cases I would expect the same values inside the @example for the object and the @example for individual fields.
To make this more clear, it would be great if I could just define:
```tsp
@example(exampleWidget)
model Widget {
@visibility("read", "update")
@path
id: string;
weight: int32;
color: "red" | "blue";
}
```
And have it _also_ fill in the examples for the id, weight, and color without me having to add those examples explicitly.
### Checklist
- [x] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [x] Read the [docs](https://typespec.io/docs/).
- [x] Check that there isn't already an issue that request the same feature to avoid creating a duplicate.
Contributor guide
Assessment
This issue has not been assessed yet.