fix(openapi): Preserve example summaries in v3 OpenAPI importer

[devin-ai-integration]

Description

Closes #9551

Fixes a bug where OpenAPI example summaries (defined via examples.<name>.summary) were being ignored in the v3 OpenAPI importer, causing the CLI to display generic "Example 1/2/3" labels instead of user-provided names like "Partner token" and "User token".

Changes Made

OpenAPI to IR Conversion

• Modified AbstractMediaTypeObjectConverter.parseMediaTypeObject() to preserve the full OpenAPIV3_1.ExampleObject (including summary and description fields) instead of extracting only the value field
• Changed lines 89 and 91 in AbstractMediaTypeObjectConverter.ts to return the complete example object rather than example.value ?? example

IR to FDR Conversion

• Updated convertV2HttpEndpointExample() in convertPackage.ts to prefer example.displayName when setting the FDR example name field
• Added logic to use displayName when present, falling back to the existing shouldUseExampleName behavior for backward compatibility
• This ensures OpenAPI example summaries are surfaced in the final FDR output used by documentation

Testing

• Added regression test in packages/cli/register/src/ir-to-fdr-converter/__test__/openapi-from-flag.test.ts following CLAUDE.md instructions
• Created test fixture with OpenAPI spec from issue OpenAPI example summaries are ignored in latest CLI version #9551
• Generated snapshot files to validate IR and FDR output
• Updated snapshots for existing tests (x-code-samples, openapi-from-flag-simple, etc.) to reflect corrected behavior

Root Cause

The bug had two parts:

1. OpenAPI → IR: In AbstractMediaTypeObjectConverter.ts, example objects were being reduced to just their values when building the examples map. This discarded the summary and description fields. The type signature already indicated it should return Record<string, OpenAPIV3_1.ExampleObject>, but the implementation was incorrectly extracting just the value.

2. IR → FDR: In convertPackage.ts, the convertV2HttpEndpointExample function only used example names when shouldUseExampleName was true (i.e., when there were duplicate status codes). This meant that even when displayName was preserved in the IR, it wasn't being surfaced in the FDR output, resulting in name: undefined for examples.

Testing

• Lint checks passed (pnpm run check)
• Regression test added following CLAUDE.md instructions
• Test validates that "Partner token" and "User token" appear in FDR output with correct names
• Test validates that generic names like "Example 1" do NOT appear
• Snapshot files generated and updated for regression testing
• All existing tests pass with updated snapshots

Review Checklist

Please verify:

1. Snapshot changes are intentional: Multiple test snapshots were updated (x-code-samples, openapi-from-flag-simple, multiple-security-headers, etc.) to show example names instead of undefined. Confirm these changes reflect the correct behavior and don't indicate unintended side effects.

2. Backward compatibility: The fix prefers example.displayName when present but falls back to the existing shouldUseExampleName logic. Verify this doesn't break any existing use cases where examples don't have displayName set.

3. Type compatibility: Confirm that downstream consumers of convertedSchema.examples (in RequestBodyConverter, ResponseBodyConverter, ResponseErrorConverter) correctly handle the full ExampleObject structure.

4. Coverage: The test covers request body examples. Consider whether response body examples might have the same issue (though they likely follow the same code path).

5. displayName usage: The fix affects all v2 examples with displayName set, not just OpenAPI examples. Verify this is the desired behavior across all example sources.

---

Link to Devin run: https://app.devin.ai/sessions/7745e59c5e534fa1bc5f6393a8ef43f4
Requested by: [email protected]

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring