microsoft / microsoft/typespec
Allow adding inline descriptions/documentation to response unions
- 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 I'm defining response types for endpoints that can return multiple different responses, I'd like to be able to add documentation to each possible response, without having to redefine the responses as aliases.
Here's an example:
```typespec
// I'd like to be able to add a @doc or comment to both of the return types.
op login(email: string, password: string): NoContentResponse | BadRequestResponse
// Doing this inline doesn't work:
op login(email: string, password: string):
/** Comment not valid here */
| NoContentResponse
| @doc("Decorator not valid here") BadRequestResponse
// Doing this in a named union doesn't work:
union LoginResponse {
/** The user was logged in successfully. */
NoContentResponse;
/** The request contained invalid fields */
BadRequestResponse;
}
// The above results in an `anyOf` component schema, even though the
// documentation is added, which is not what I want.
```
The only thing that works is the following:
```typespec
// Using a `model is` and then documenting it:
/** The user was logged in successfully. */
model LoginNoContentResponse is NoContentResponse;
// Or an alias
/** The request contained invalid fields */
alias LoginBadRequestResponse = BadRequestResponse;
op login(email: string, password: string): LoginNoContentResponse | LoginBadRequestResponse;
```
This feels _very_ boilerplat-ey. I have to think of a naming convention for the aliases/models and type every response type twice.
The union version working would be fine with me, but being able to do it inline would be the best.
### 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.