Allow description and summary in examples with OpenAPI 3.1 emitter

[dfioravanti]

Disclaimer: I raised this in #5713 which was closed but I do not 100% agree with the reason why it was closed so I would like to propose this again.

OpenAPI 3.1 allows multiple examples which is great when one has multiple use cases for the same endpoint. The multiple examples are supported by typespec with the OpenAPI 3.1 emitter but typespec does not support setting titles and descriptions for the examples, which makes it harder for end users to understand

So for example

import "@typespec/http";
import "@typespec/openapi3";

using TypeSpec.Http;

@service({
  title: "Widget Service",
})

namespace X;

@example(#{ name: "Max", age: 3 }, #{ title: "Minimal examples", description: "Minimal examples" })
@example(
  #{ name: "Rex", age: 8, bark: true },
  #{ title: "With optional properties", description: "Example where the pet barks" }
)
model Pet {
  name: string;
  age: int32;
  bark?: boolean;
}

compiles to

openapi: 3.1.0
info:
  title: Widget Service
  version: 0.0.0
tags: []
paths: {}
components:
  schemas:
    Pet:
      type: object
      required:
        - name
        - age
      properties:
        name:
          type: string
        age:
          type: integer
          format: int32
        bark:
          type: boolean
      examples:
        - name: Rex
          age: 8
          bark: true
        - name: Max
          age: 3

it would be nice if the description and the summary was in the generated file. When I reported the bug I was told that description is deprecated in examples, but this does not seams to be the case. See here. What do people think? Am I the only one that would find this useful?

[timotheeguerin]

When I reported the bug I was told that description is deprecated in examples
as in openapi3 deprecated it or we did in Typespec?

I don't think thats the case in the later, where did you hear that?

And yeah this seems like a missing piece we forgot to add when making openapi3.1

[dfioravanti]

It was what I was told when I reported the bug, you can see it here. To me it looks like a small gap on typespec side but I did not want to keep spamming the bug report

[timotheeguerin]

ah I see, got confused as well, yeah I think from what I see this is a limitation with openapi3.1 no? This ExampleObject doesn't apply to the examples: any[] property that is found on schemas. So with that I don't think we can do much more

[dfioravanti]

I think I finally wrapped my head around about my confusion. Basically what the spec and your colleague are saying is that I should attach the samples to the application/json media-type and not to the schema? Basically (from here)

 requestBody:
  content:
    'application/json':
      schema:
        $ref: '#/components/schemas/Address'
      examples:
        foo:
          summary: A foo example
          value:
            foo: bar
        bar:
          summary: A bar example
          value:
            bar: baz

But is it even possible to represent this with typespec? If it is not the case, could it be possible to add it as an improvement down the line?