Repository navigation
fix(openapi3): import response media type examples as @opExample - #12629
Vincent Biret (baywet) wants to merge 5 commits into
Conversation
…sponse shapes Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
…response import Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
…ples Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
|
You can try these changes here
|
commit: |
|
All changed packages have been documented.
Show changes
|
There was a problem hiding this comment.
🟡 Changes recommended
An unresolved response-matching ambiguity attaches default JSON payloads to the 200 response, while schema-validation defects can emit non-compiling examples or reject valid payloads.
5 open issues
Ambiguous default response examples match the 200 response · New Nullable anyOf examples generate unassignable model values · New Flattening allOf drops inherited additionalProperties · New Numeric examples outside compiler ranges pass validation · New Primitive enum and const schemas miss JSON media-type detection · New
What changed in this PR
This PR addresses #12627 by importing OpenAPI response media-type examples as TypeSpec @opExample return values, preserving payload examples during conversion and re-emission.
Changes:
- Imports singular and named examples, local references, and supported typed payloads.
- Uses generated response shapes to route examples by status and media type, with diagnostics for unsupported cases.
- Adds compilation and round-trip tests and documents the named-summary fidelity limitation.
| File | Description |
|---|---|
packages/openapi3/test/tsp-openapi3/response-examples.test.ts |
Adds conversion, routing, round-trip, and diagnostic tests. |
packages/openapi3/src/types.ts |
Allows references in media-type example maps. |
packages/openapi3/src/cli/actions/convert/utils/response-properties.ts |
Shares response property construction and detects example-routing needs. |
packages/openapi3/src/cli/actions/convert/transforms/transforms.ts |
Uses shared component-response properties. |
packages/openapi3/src/cli/actions/convert/transforms/transform-component-schemas.ts |
Exports generated-type classification for example conversion. |
packages/openapi3/src/cli/actions/convert/generators/generate-response-expressions.ts |
Builds example shapes alongside response types and routing metadata. |
packages/openapi3/src/cli/actions/convert/generators/generate-response-examples.ts |
Resolves, validates, and generates response example decorators. |
packages/openapi3/src/cli/actions/convert/generators/generate-operation.ts |
Adds generated example decorators to operations. |
.chronus/changes/copilot-tsp-openapi3-import-response-examples-2026-10-20-18-40-42.md |
Documents the converter fix and fidelity limitations. |
Review effort: Balanced
| examples.push( | ||
| ...generateResponseExamples( | ||
| { statusCode: "default", mediaType, content, properties }, |
There was a problem hiding this comment.
Fixed in d6e9b22 by excluding concrete responses when their required status discriminator is absent; added a scalar default-response round-trip regression.
| const resolved = context.getSchemaByRef(schema.$ref); | ||
| if (!resolved) return invalid(); |
There was a problem hiding this comment.
Fixed in d6e9b22: null values for referenced components generated as models are diagnosed and skipped, with regression coverage.
| properties = { ...properties, ...s.properties }; | ||
| for (const key of s.required ?? []) required.add(key); |
There was a problem hiding this comment.
Fixed in d6e9b22 by retaining and validating inherited record indexers, with valid and invalid round-trip examples.
| const primitive = getTypeSpecPrimitiveFromSchema(schema); | ||
| if (primitive === "duration" || primitive === "utcDateTime") return invalid(); | ||
| const integer = /^(u?)int(8|16|32|64)$/.exec(primitive ?? ""); |
There was a problem hiding this comment.
Fixed in d6e9b22: numeric types are normalized before range checks, including float32 and safeint bounds; added boundary and rejection tests.
| return isScalarBody(context.getSchemaByRef(schema.$ref), context, seen); | ||
| } | ||
| return ( | ||
| schema.type === "string" || |
There was a problem hiding this comment.
Fixed in d6e9b22: primitive enum and const values trigger explicit content-type routing; both cases have round-trip coverage.
|
Copilot address the review comments, reply and resolve |
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>


Response Media Type Object examples were dropped during OpenAPI conversion, losing payload examples on round-trip emission.
@opExample.returnType, including local Example Object references, arrays, falsy/null values, and typed scalars.example/examplesfields, unsupported values, and unrepresentable or ambiguous branches while retaining other valid examples.For an inline JSON response with status
201:The status and wrapper route the example; the emitted payload remains
{ "name": "demo" }.