microsoft / microsoft/typespec

[Bug]: getStatusCodeDescription limits doc decorator defined in models of type Response

Open
#4,796 3 comments 0 reactions 0 assignees View on GitHub
compiler:core design:needed triaged:core
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

### Describe the bug

As of recently it seems like the doc decorator in models of type Response is ignored and the descriptions set in the rangeDescription function are forced based on the status code. Is it possible to reset this so that the doc decorator overrides the default responses?

![Image](https://github.com/user-attachments/assets/9050d813-1d01-4b6c-a650-20ac4290a103)

### Reproduction

The following typespec example:

```typespec
@error
model Error {
@doc("Error code")
code: string;
@doc("Error description")
description: string;
}

@doc("Method not allowed")
model MethodNotAllowedResponseis Response<405>;

alias ErrorType = (MethodNotAllowedResponse & Error);

@route("/sample")
interface SamplesInterface {
@get list(): SampleList | ErrorType;
```

generates the following:

```yaml
.....
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/SampleList'
'405':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
......
```

instead of

```yaml
......
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/SampleList'
'405':
description: Method not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
.......
```

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