You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Now that #2700 is complete, the tsp-openapi tool should be updatet to do the reverse and add example(s) to the TypeSpec. (A single opExample/example if using example, multiple if using examples.)
I verified a concrete Schema Object round-trip case with @typespec/openapi31.18.0, using OpenAPI 3.2.0 for both input and output. This is about the JSON Schema examplesarray, not the named examples map on an OpenAPI Media Type Object.
Repro
Save this as openapi.yaml and run tsp-openapi3 openapi.yaml --output-dir converted:
Actual: The converter emits the model with the required name property, but silently drops the entire examples array. The generated declaration has no @example decorators:
modelPet {
name:string;
}
Expected: Import each array entry as its own @example decorator on Pet. Re-emitting to OpenAPI 3.2.0 should produce a single components.schemas.Pet.examples array containing all three instance values, without a singular example field. The desired round trip preserves the original array order as well as the values.
Emitter behavior to account for
No emitter feature is needed to represent multiple schema examples: I also verified that repeated @example decorators on a model already emit a single schema-level examples array in 3.2.0. In 1.18.0 the emitted order is the reverse of the written decorator order. For this input, writing the decorators in the following order would account for that behavior:
A regression test could import this fixture, compile the generated TypeSpec, re-emit OpenAPI 3.2.0, and compare components.schemas.Pet.examples to the input array. A one-entry array is also worth covering: it should still round-trip as examples: [...], not as the deprecated OpenAPI Schema Object example field. Media Type Object example maps and their Example Object metadata are a separate case.
I opened #12627 to track importing OpenAPI response media-type example and examples as @opExample.returnType. It includes a minimal repro and round-trip cases for multiple response statuses, media types, and named examples.
Activity
Arithmomaniac commentedon Aug 1, 2024
Mark Cowlishaw (@markcowl) Timothee Guerin (@timotheeguerin) thanks for backlogging, hopefully it can at least be in beta by Hack
baywet commentedon Nov 20, 2026
I verified a concrete Schema Object round-trip case with
@typespec/openapi31.18.0, using OpenAPI 3.2.0 for both input and output. This is about the JSON Schemaexamplesarray, not the namedexamplesmap on an OpenAPI Media Type Object.Repro
Save this as
openapi.yamland runtsp-openapi3 openapi.yaml --output-dir converted:Actual: The converter emits the model with the required
nameproperty, but silently drops the entireexamplesarray. The generated declaration has no@exampledecorators:Expected: Import each array entry as its own
@exampledecorator onPet. Re-emitting to OpenAPI 3.2.0 should produce a singlecomponents.schemas.Pet.examplesarray containing all three instance values, without a singularexamplefield. The desired round trip preserves the original array order as well as the values.Emitter behavior to account for
No emitter feature is needed to represent multiple schema examples: I also verified that repeated
@exampledecorators on a model already emit a single schema-levelexamplesarray in 3.2.0. In 1.18.0 the emitted order is the reverse of the written decorator order. For this input, writing the decorators in the following order would account for that behavior:A regression test could import this fixture, compile the generated TypeSpec, re-emit OpenAPI 3.2.0, and compare
components.schemas.Pet.examplesto the input array. A one-entry array is also worth covering: it should still round-trip asexamples: [...], not as the deprecated OpenAPI Schema Objectexamplefield. Media Type Object example maps and their Example Object metadata are a separate case.References: OpenAPI 3.2.0 Schema Object and JSON Schema Draft 2020-12
examples.baywet commentedon Nov 20, 2026
I opened #12627 to track importing OpenAPI response media-type
exampleandexamplesas@opExample.returnType. It includes a minimal repro and round-trip cases for multiple response statuses, media types, and named examples.