fix(openapi): prioritize property-level examples over referenced schema examples

[devin-ai-integration]

Description

Linear ticket: Closes #7932

When an OpenAPI 3.1+ schema property has both a $ref and example/examples fields (which is valid in OpenAPI 3.1+), the parser now correctly prioritizes the property-level examples over the examples from the referenced schema.

Previously, if you had:

properties:
  logo:
    $ref: '#/components/schemas/File'
    examples:
      - url: https://images.example.com/logo.png

The parser would use the examples from the File schema instead of the property-level examples. This fix ensures property-level examples take precedence.

Changes Made

• Modified new v3 parser only (v3-importer-commons/ConvertProperties.ts) to extract and prioritize property-level examples
• Added type guard hasExamples() to safely detect schemas with example/examples fields (works for both SchemaObjects and ReferenceObjects with siblings)
• Property-level example and examples fields are now extracted before schema conversion
• When properties have their own examples, these are used to populate v2Examples instead of falling back to type declaration examples
• Example keys use consistent naming convention ({propertyId}_example_{index}) to maintain backward compatibility with existing IR contract
• Updated snapshot tests to reflect the new example extraction behavior (6 files in v3-importer-tests)
• Added comprehensive test case in packages/cli/register that validates property-level example precedence through the complete --from-openapi pipeline
• Note: The old parser (openapi-ir-parser) was NOT modified because it uses OpenAPI 3.0 types which don't support the examples property. This fix only applies to the v3 parser which handles OpenAPI 3.1+ specs.
• Updated README.md generator (if applicable)

Testing

✅ All tests pass - The fix is verified to work correctly:

• NEW: Dedicated test case in packages/cli/register/src/ir-to-fdr-converter/__test__/openapi-from-flag.test.ts
  • Test fixture: fixtures/property-level-examples/ with OpenAPI spec matching issue OpenAPI: Property-level examples for $ref properties are ignored #7932
  • Validates that Company.logo uses property-level example (logo.png) instead of File schema example (invoice.pdf)
  • Tests complete pipeline: OpenAPI → IR → FDR (S3-ready format)
  • Includes snapshot regression testing
• Snapshot tests in packages/cli/register pass locally
• Snapshot tests in packages/cli/api-importers/v3-importer-tests pass locally (6 files updated)
• Tests confirm property-level examples are extracted and used
• Example key naming maintains backward compatibility with existing IR structure
• ✅ All CI checks passing (70/70)

Updates Since Last Revision

Maintenance Updates (Latest commits)

• Resolved merge conflict markers that were left in test file after merging main
• Applied biome formatting fixes to test file
• Updated snapshot to include isWildcardStatusCode field (this field was added to the IR in main via commit 9d9a902 for 4XX/5XX support - unrelated to this PR)
• All changes verified locally before pushing

Test Case Added (Previous commit)

• Added comprehensive test case following CLAUDE.md testing conventions
• Test validates the exact scenario from issue OpenAPI: Property-level examples for $ref properties are ignored #7932: property with $ref + examples siblings
• Fixture includes Company schema with logo property that references File schema but provides property-level examples
• Test assertions verify:
  • Property-level examples are present in IR (logo.png)
  • Schema-level examples are NOT used (invoice.pdf is absent)
  • Complete --from-openapi pipeline produces correct FDR output
• Snapshots generated for regression testing

Snapshot Updates (Earlier commit)

• Updated 6 snapshot files in v3-importer-tests to reflect the new example extraction behavior
• Changes include:
  • Property ordering differences in example objects (JSON objects are unordered by spec, so this is benign)
  • More examples now populated in v2Examples.userSpecifiedExamples where property-level examples exist
  • Some literal types converted to named enum types (e.g., literal: "error" → named: "ErrorStatus") - this appears to be a side effect of improved type extraction

Human Review Checklist

Critical items to verify:

• MOST IMPORTANT: Confirm CI passes completely (proves the mechanism works for v3 importer) - ✅ All 70 checks passing
• Verify new test case: Review the test in openapi-from-flag.test.ts and confirm it properly validates the fix
• Verify literal → enum conversion: The snapshot diffs show single-value literals being converted to named enum types (e.g., ErrorStatus, CircleType, SquareType). Confirm this is expected behavior and doesn't break downstream generators. This is a significant behavioral change that could affect SDK generation.
• Property ordering: Confirm that property ordering changes in example objects don't affect any consumers that might serialize/compare examples textually.
• Test with the exact YAML from issue OpenAPI: Property-level examples for $ref properties are ignored #7932 to confirm the specific reported case works (test case should cover this)
• Test all variants mentioned in the issue:
  • $ref + example (singular) ✅ Covered by test
  • $ref + examples (array) ✅ Covered by test
  • allOf: [$ref] + examples ⚠️ Not explicitly tested
  • allOf: [$ref, {examples: ...}] ⚠️ Not explicitly tested
• Verify workspace-based OpenAPI imports (api: specs: - openapi:) use the v3 parser and benefit from this fix (currently unverified)

Implementation notes:

• Uses type guard hasExamples() to safely detect schemas with example/examples fields: typeof schema === "object" && schema != null && ("example" in schema || "examples" in schema)
• Type guard works for both SchemaObjects and ReferenceObjects (necessary for OpenAPI 3.1+ support where $ref can have siblings)
• Fix applied in convertProperties function before calling SchemaOrReferenceConverter
• Property-level examples are extracted into propertyLevelExamples array and used to populate v2Examples on the property
• Falls back to type declaration examples if no property-level examples exist
• Example keys follow existing convention: {propertyId}_example_{index}

Known risks:

• ⚠️ Snapshot changes beyond property ordering: Some literal types are being converted to named enum types. This may be correct behavior but should be verified with the team as it could affect SDK generation.
• ⚠️ Workspace import path unverified: We haven't confirmed that workspace-based imports (api: specs: - openapi: ../openapi.yml) use the v3 parser. If they use the old parser, they won't benefit from this fix.
• ⚠️ allOf variants untested: The allOf: [$ref, {examples: ...}] pattern from the issue hasn't been explicitly tested in the new test case.

Scope limitation:

• This fix only applies to the new v3 parser (openapi-to-ir/v3-importer-commons)
• Users relying on the old parser (openapi-ir-parser) will not benefit from this fix
• If workspace-based imports use the old parser, they won't benefit from this fix either

---

Devin session: https://app.devin.ai/sessions/eb789030add4441bb97a4b6a2eb22a80
Requested by: @dannysheridan

[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