microsoft / microsoft/typespec

Provide mechanism to add docs to adhoc return types inline

Open
#3,075 0 comments 3 reactions 0 assignees View on GitHub
design:needed 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

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

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.