How to generate example in OpenAPI3

[ouvreboite]

I see that generating per-field example in OpenAPIv3 is not supported (cf typespec-for-openapi).

Is there a specific reason for that, or are you open for a PR to add this support?

[timotheeguerin]

Hi, we have an implementation issue that hasn't been implemented yet https://github.com/microsoft/typespec/issues/2700

However it is a little bigger than just openapi3 examples. We are definitely open to PR and if you are intrested in implementing on the decorator and openapi3 part (without the versioning) I think that would be fair to split.

[ouvreboite]

That's nice to hear :)

The linked PR (https://github.com/microsoft/typespec/issues/2700) seems broader, as it tries to tackle both "object" examples and "per property" examples. I would rather focus on "per property" example first, as it would have no impact on versioning and be simpler to implement.

Something like that:

model Person
{   
    @example("Alice")
    name: string;

    @example(42) 
    @added(Versions.v2) 
    age: int32;
}

[markcowl]

@ouvreboite That is covered by #2700, although the 'simple' example is a bit buried in the details:

model Foo {
  type: "bar" | "baz"
  @jsonExample("2023-03-01T19:00:00Z")
  createdAt: utcDateTime;
}

Which for your example would be:

model Person
{   
    @jsonExample("Alice")
    name: string;

    @jsonExample(42) 
    @added(Versions.v2) 
    age: int32;
}

[markcowl]

Note that, even property examples potentially have versioning implications, as example values can become obsolete over time

[markcowl]

@ouvreboite Please let us know if this implementation will enable what you need, or if you have questions or concerns.

[ouvreboite]

@markcowl LGTM :)

[tobiashochguertel]

When can I use this or test it?

[tobiashochguertel]

I use OpenAPI-to-postman to generate a postman collection from my typespec to OpenAPI generated OpenAPI spec, and add via jq some missing things like auth and pre-request script (to generate an authorization token) before a request, to quickly test the new API spec via postman.

Now, it would make sense for me to also define examples in typespec and have them then also in the generated OpenAPI spec.

Here is my scripts section from the package.json file of my typespec project:

    "scripts": {
        "compile": "tsp compile .",
        "dev": "npx nodemon --watch dist --watch . -e tsp --exec \"npm run compile\"",
        "postman:generate": "openapi2postmanv2 -s tsp-output/@typespec/openapi3/openapi.2.0.0.yaml -o tsp-output/@typespec/postman/collection.json -p -c ./cli-options-config.json",
        "jq:remove:event": "jq 'del(.event)' ./tsp-output/@typespec/postman/collection.json > tsp-output/@typespec/postman/collection.clean.json",
        "jq:add:auth": "jq -s add auth.json tsp-output/@typespec/postman/collection.clean.json > tsp-output/@typespec/postman/collection.auth.json",
        "jq:add:event": "jq -s add event.json tsp-output/@typespec/postman/collection.auth.json > tsp-output/@typespec/postman/collection.event.json",
        "jq:cleanup:collection.json": "rimraf tsp-output/@typespec/postman/collection.json",
        "jq:cleanup:collection.clean.json": "rimraf tsp-output/@typespec/postman/collection.clean.json",
        "jq:cleanup:collection.auth.json": "rimraf tsp-output/@typespec/postman/collection.auth.json",
        "_jq:cleanup:collection.event.json": "rimraf tsp-output/@typespec/postman/collection.event.json",
        "postman": "npm run postman:generate && npm run jq:remove:event && npm run jq:add:auth && npm run jq:add:event && npm run jq:cleanup:collection.json && npm run jq:cleanup:collection.clean.json && npm run jq:cleanup:collection.auth.json"
    }

[markcowl]

We are adding some new capabilities to OpenAPI for representing value types: https://github.com/microsoft/typespec/issues/2046

We are integrating this into the Sample design and should have an updated design this month, with implementation to follow next month.

[KieranP]

@markcowl Has there been any progress on this? I have been porting a large OpenAPI file to Typespec today, and almost everything we need is supported except Examples for properties, which has meant we need to put the conversion on hold until it is supported.

[timotheeguerin]

we have agreed on the first version of the updated design and should be working on it soon, planning for this incoming sprint(releasing next month as we are just about to release today)

[dmunch]

great news! The first version of the updated design, is it the one you've outlined here ? Very keen to get my hands on this - Just been starting to use TypeSpec for a new service and found it great so far, but really am missing the possibility to add examples for OpenAPI.

[timotheeguerin]

Yea that one except all the scoping was cut for now, just a single arg with the example

[timotheeguerin]

Will actually close this issue in favor of the other one https://github.com/microsoft/typespec/issues/2700, I have started working on it, Playground demo

PR https://github.com/microsoft/typespec/pull/3572 if you have feedback