microsoft / microsoft/typespec

Allow adding inline descriptions/documentation to response unions

Open
#8,148 1 comment 1 reaction 0 assignees View on GitHub
compiler:core feature triaged:core
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

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.