Skip to content

fix(openapi3): import response media type examples as @opExample - #12629

Draft
Vincent Biret (baywet) wants to merge 5 commits into
mainfrom
copilot/tsp-openapi3-import-response-examples
Draft

Vincent Biret (baywet) wants to merge 5 commits into
mainfrom
copilot/tsp-openapi3-import-response-examples

Conversation

@baywet

@baywet Vincent Biret (baywet) commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Response Media Type Object examples were dropped during OpenAPI conversion, losing payload examples on round-trip emission.

  • Import: Convert singular and named examples into @opExample.returnType, including local Example Object references, arrays, falsy/null values, and typed scalars.
  • Routing: Construct values from generated response shapes, preserving body wrappers and status/media-type discriminators without treating payload fields as metadata.
  • Fidelity: Preserve named keys and descriptions without collapsing identical payloads. Keys become decorator titles—and emitted summaries—so distinct source summaries cannot currently be retained.
  • Diagnostics: Skip conflicting example/examples fields, unsupported values, and unrepresentable or ambiguous branches while retaining other valid examples.

For an inline JSON response with status 201:

@opExample(#{ returnType: #{ statusCode: 201, body: #{ name: "demo" } } })

The status and wrapper route the example; the emitted payload remains { "name": "demo" }.

…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>
@microsoft-github-policy-service microsoft-github-policy-service Bot added emitter:openapi3 Issues for @typespec/openapi3 emitter openapi3:converter Issues for @typespec/openapi3 openapi to typespec converter labels Nov 20, 2026
…ples

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
@baywet Vincent Biret (baywet) changed the title [WIP] Add import for response media type examples as @opExample returnType fix(openapi3): import response media type examples as @opExample Nov 20, 2026
@azure-sdk-automation

azure-sdk-automation Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

You can try these changes here

🛝 Playground 🌐 Website 🛝 VSCode Extension

@pkg-pr-new

pkg-pr-new Bot commented Nov 20, 2026

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/openapi3@12629

commit: 0a0d024

@github-actions

Copy link
Copy Markdown
Contributor

All changed packages have been documented.

  • ✅ @typespec/openapi3
Show changes

@typespec/openapi3 - fix ✏️

[converter] Import response media type examples as operation return examples, preserving response status, media type, named keys, and descriptions. Named keys become decorator titles (and emitted summaries), so distinct source summaries cannot currently be retained. Conflicting example/examples fields are diagnosed and skipped. Unsupported values, required headers without values, status ranges, stream/item examples, and media types absent from generated component response models are diagnosed without discarding other valid examples.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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
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

Comment on lines +217 to +219
examples.push(
...generateResponseExamples(
{ statusCode: "default", mediaType, content, properties },

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d6e9b22 by excluding concrete responses when their required status discriminator is absent; added a scalar default-response round-trip regression.

Comment on lines +166 to +167
const resolved = context.getSchemaByRef(schema.$ref);
if (!resolved) return invalid();

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d6e9b22: null values for referenced components generated as models are diagnosed and skipped, with regression coverage.

Comment on lines +240 to +241
properties = { ...properties, ...s.properties };
for (const key of s.required ?? []) required.add(key);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d6e9b22 by retaining and validating inherited record indexers, with valid and invalid round-trip examples.

Comment on lines +316 to +318
const primitive = getTypeSpecPrimitiveFromSchema(schema);
if (primitive === "duration" || primitive === "utcDateTime") return invalid();
const integer = /^(u?)int(8|16|32|64)$/.exec(primitive ?? "");

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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" ||

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d6e9b22: primitive enum and const values trigger explicit content-type routing; both cases have round-trip coverage.

@baywet

Copy link
Copy Markdown
Member Author

Copilot address the review comments, reply and resolve

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Copilot AI commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

Copilot address the review comments, reply and resolve

Addressed all five findings in d6e9b22 and replied on each thread. The OpenAPI package suite passes (2,811 tests). I couldn’t resolve the threads because the available tools don’t support resolving review conversations.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

emitter:openapi3 Issues for @typespec/openapi3 emitter openapi3:converter Issues for @typespec/openapi3 openapi to typespec converter

Projects

None yet

Development

Successfully merging this pull request may close these issues.

tsp-openapi3: import response media type examples as @opExample returnType

3 participants