microsoft / microsoft/typespec
Provide mechanism to add docs to adhoc return types inline
- Dominant language
- Java
- Stars
- 5.9k
- Forks
- 394
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 104
Description
### Clear and concise description of the problem
### Discussed in https://github.com/microsoft/typespec/discussions/3074
Originally posted by **LadyCailin** March 28, 2024
I could just be doing something wrong here, which is why I don't want to file a bug yet, but I'm having trouble understanding how to replicate my existing openapi spec, where I document individual return codes. Here's what I've tried so far:
https://typespec.io/playground?c=aW1wb3J0ICJAdHlwZXNwZWMvaHR0cCI7DQp1c2luZyBUeXBlU3BlYy5IdHRwOw0KDQpAdGFnKCJmb28iKQ0KaW50ZXJmYWNlIGZvbyB7DQogIEByb3V0ZSgiL8QgICBAZ2V0xB0oKTrGICAgQHN0YXR1c0NvZGUgygs6IDIwMDvHImRvYygiVGhlc2UgZG9jcyBkb24ndCBzaG93LsZXICBAYm9kecYLxAo6IHN0cmluZ8VCfSB8320gNDAz1W0sIGJ1dCBpdCBpc8RzYSBwcm9wZXJ0ecl50m47DQp9&e=%40typespec%2Fopenapi3&options=%7B%7D
```
@get foo(): {
@statusCode statusCode: 200;
@doc("These docs don't show.")
@body
body: string;
} | {
@statusCode statusCode: 403;
@doc("These do, but it isn't a property.")
body: string;
};
```
With this, I end up with:
```
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
type: string
'403':
description: Access is forbidden
content:
application/json:
schema:
type: object
properties:
body:
type: string
description: These do, but it isn't a property.
required:
- body
```
The original spec that I am trying to more or less end up with is this:
```
"200":
description: Description of what happens with 200s
content:
text/plain:
schema:
type: string
"403":
description: Description of why 403 would happen
```
Anyways, I very well could be missing something here about how to properly add return value docs, any help would be appreciated!
At the bottom of the discussion is a proposal using union return types instead of adhoc objects, which seems a reasonable solution.
### 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.