fix(cli): convert invalid Swagger 2.0 specs in lenient mode

[devin-ai-integration]

Description

Linear ticket: Refs

convertOpenAPIV2ToV3 calls swagger2openapi with no options, so any Swagger 2.0 document that trips a patchable error fails to convert. OpenAPILoader catches that failure at debug level and returns undefined, so the spec is silently dropped from the docs/SDK build with no user-visible reason.

Real case: Autodesk's ACC Admin Swagger files declare type: ['null', string] on several properties (invalid in both Swagger 2.0 and OpenAPI 3.0). swagger2openapi throws (Patchable) schema type must not be an array, and all three specs vanish. Passing patch: true converts them cleanly, mapping the type array to nullable: true.

Rather than making lenient conversion the default, this keeps strict conversion as the primary path and falls back once:

try { return (await convertObj(openAPI, {})).openapi; }
catch (error) { strictError = error; }
try {
  const result = await convertObj(openAPI, { patch: true });
  context?.logger.warn(`...converted in lenient (patch) mode: ${strictError.message}`);
  return result.openapi;
} catch { throw new CliError({ /* strictError.message */ }); }

The thrown error still reports the strict message, which is the informative one. convertObj deep-clones its input (cclone), so the retry sees the original document, not a partially converted one.

Changes Made

• convertOpenAPIV2ToV3 retries once with { patch: true } when strict conversion fails, and warns when the fallback succeeds so the leniency isn't invisible.
• Added an optional options?: { context?: TaskContext } parameter for that warning, passed from the OpenAPILoader call site. The parameter is optional, so the oss-validator call sites (which have no TaskContext) are unchanged.
• Updated README.md generator (if applicable)

Testing

• Unit tests added/updated — new convertOpenAPIV2ToV3.test.ts: valid v2 document converts to 3.0.x; a document with type: ['null', 'string'] converts via the fallback to type: "string" / nullable: true and emits the warning; an unconvertible document still throws CliError.
• Manual testing completed — pnpm --filter @fern-api/lazy-fern-workspace test (100 tests, 12 files, all passing, including the existing loadOpenAPI suite), pnpm turbo run compile --filter='@fern-api/lazy-fern-workspace...' (29 tasks successful), and biome check clean on the touched files.

No seed fixture was added: test-definitions/ has no Swagger 2.0 (swagger: "2.0") fixture precedent to follow, and this change is in the workspace loader rather than in api-importers/openapi.

Link to Devin session: https://app.devin.ai/sessions/607a35683f974cda9bb45321b9372852

---

[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, CI, and merge conflict monitoring

[devin-ai-integration]

Devin Review found 1 potential issue.

[github-actions]

Docs Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-08-24T04:15:25Z).

Fixture	main	PR	Delta
docs	270.7s (n=5)	264.5s (35 versions)	-6.2s (-2.3%)

Docs generation runs fern generate --docs --preview end-to-end against the benchmark fixture with 35 API versions (each version: markdown processing + OpenAPI-to-IR + FDR upload).
Delta is computed against the nightly baseline on main.
Baseline from nightly run(s) on main (latest: 2026-08-24T04:15:25Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-08-24 22:35 UTC

[github-actions]

SDK Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-08-24T04:15:25Z).

Full benchmark table (click to expand)

Generator	Spec	main (generator)	main (E2E)	PR (generator)	Delta
csharp-sdk	square	75s (n=5)	113s (n=5)	90s	+15s (+20.0%)
go-sdk	square	137s (n=5)	298s (n=5)	122s	-15s (-10.9%)
java-sdk	square	239s (n=5)	285s (n=5)	200s	-39s (-16.3%)
php-sdk	square	64s (n=5)	N/A	55s	-9s (-14.1%)
python-sdk	square	152s (n=5)	252s (n=5)	118s	-34s (-22.4%)
ruby-sdk-v2	square	95s (n=5)	125s (n=5)	105s	+10s (+10.5%)
rust-sdk	square	228s (n=5)	215s (n=5)	211s	-17s (-7.5%)
swift-sdk	square	60s (n=5)	450s (n=5)	53s	-7s (-11.7%)
ts-sdk	square	138s (n=5)	150s (n=5)	110s	-28s (-20.3%)

main (generator): generator-only time via --skip-scripts (includes Docker image build, container startup, IR parsing, and code generation — this is the same Docker-based flow customers use via fern generate). main (E2E): full customer-observable time including build/test scripts (nightly baseline, informational). Delta is computed against generator-only baseline.
⚠️ = generation exited with a non-zero exit code (timing may not reflect a successful run).
Baseline from nightly runs on main (latest: 2026-08-24T04:15:25Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-08-24 22:35 UTC