feat(openapi): Add generator support for OpenAPI overlays specs

[schottra]

Description

Linear ticket: Refs https://linear.app/buildwithfern/issue/FER-8144/add-openapi-overlays-support

Changes Made

(note: merging to a feature branch, needs more work to be feature complete)

See the announcement and spec for context.

• Added core util to apply an overlay to a spec object, including a smattering of tests to try and exercise all the edge cases in the spec
• Added test fixture with a sample overlay and snapshots to exercise the generator path
• Updated generation code paths to support overlay field in YAML, read the file, and use the helper to apply it after overrides

I copied the test fixture for applying overrides, so it's not exhaustive.

Open Questions / Issues

The test fixture for overlays was based on the overrides fixture next to it. However, when generated, the snapshot has one reference to UserSettings which ends up typed as unknown in the overlays code path. At first glance I'm not sure what's causing this, but wonder if it's something to with refs not getting copied over correctly.

Do we need to add this support to https://github.com/fern-api/fern/blob/066edd00e9d74464fd150839fb539c716efd6d66/packages/cli/workspace/browser-compatible-fern-workspace/src/InMemoryOpenAPILoader.ts as well?

Testing

Unit and snapshot tests cover this change for now. I haven't manually tested it, would do that as part of merging the feature branch.

TODO / Follow-ons

• Add instructions for using overlays to public docs

[github-actions]

🌱 Seed Test Selector

Select languages to run seed tests for:

• Python
• TypeScript
• Java
• Go
• Ruby
• C#
• PHP
• Swift
• Rust
• OpenAPI
• Postman

---

How to use: Click the ⋯ menu above → "Edit" → check the boxes you want → click "Update comment". Tests will run automatically and snapshots will be committed to this PR.

[fern-support]

I think this should be a warning, it shouldn't fail anything.

[schottra]

Practically speaking I agree. This was meant to enforce a rule in the Overlays spec:
REQUIRED An ordered list of actions to be applied to the target document. The array MUST contain at least one value.

[fern-support]

A couple of comments:

• The problem with $ref resolving can be solved, I think, not worried about it
• William pointed me to the immer module that helps with mutating data structures. I think this may be relevant here, too.

I asked Claude to review the PR, and it had some helpful feedback, but nothing worth holding the PR back on. I recommend asking it to review and doing some polishing based on that.