Documenting return properties in openapi3 emitter

[LadyCailin]

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!

[timotheeguerin]

I do think we cannot do that today inline as you want, you have 2 options:

1. Create a seperate response model and the doc on the model will be used on the repsonse
2. Use @returns/@errors doc comment tags(or @returnsDoc, @errorsDoc decorators) to specify the doc for success and error cases. However those will be providing the doc for all success and all errors respectively so if you want more granular doc you'll have to go with option 1

Playground Example

[LadyCailin]

Aha, option 1 works for me, so I'll do that. Though I think it would still be good to have a way to do this with the adhoc return types too.

{
    @statusCode statusCode: 200;
    @doc("These docs don't show.")
    @body
    body: string;
 }

This syntax seems intuitive to me, but perhaps you have better ideas.

[timotheeguerin]

The problem with response docs is always the question of who wins if you specify docs in multiple places. Assuming the example you had above was working, what if you also had the doc on the model itself and with @errors in the doc comment? It gets a little tricky to override the doc when you are trying to reuse a common model provided by library you don't control.

However there might be a good solution to all of this, I do agree that it would be nice to be able to provide it inline. One of the backlog items is being able to provide statement decalaration as expression, e.g.

op test(): union {
  202: {},
  @doc("This is the 403 doc")
  403: {}
}

this I think would make a lot of sense.

Feel free to file a feature request.