Fix gen-openapi to quote OpenAPI version fields for Mintlify validation

[monadoid]

why

Mintlify requires OpenAPI version fields to be strings and only accepts spec files inside the docs repo. Unclear why this only recently started failing.

what changed

Quote openapi and info.version during OpenAPI generation and point Mintlify at a symlinked openapi.v3.yaml inside packages/docs.

test plan

Confirmed that changes generates correct openapi spec.

---

Summary by cubic

Quote OpenAPI version fields in the generated YAML so Mintlify validation passes. Fixes errors caused by bare numeric openapi and info.version values.

• Bug Fixes
  • Post-process generated YAML in gen-openapi.ts to quote openapi and info.version.
  • Update openapi.v3.yaml to use quoted strings ("3.1.0") for both fields.

^{Written for commit aad5e16. Summary will update on new commits. Review in cubic}

[changeset-bot]

⚠️ No Changeset found

Latest commit: aad5e16

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

✱ Stainless preview builds

This PR will update the stagehand SDKs with the following commit message.

feat: Fix gen-openapi to quote OpenAPI version fields for Mintlify validation

⚠️ stagehand-csharp studio · code

There was a regression in your SDK.
generate ⚠️ → build ✅ → lint ❗ → test ❗

✅ stagehand-go studio · code

Your SDK built successfully.
generate ✅ → lint ✅ → test ✅

go get github.com/stainless-sdks/stagehand-go@71e04b802bb81c407751c299d700a5e2c93db119

❗ stagehand-python studio

Code was not generated because there was a fatal error.

✅ stagehand-openapi studio · code

Your SDK built successfully.
generate ✅

⚠️ stagehand-typescript studio · code

There was a regression in your SDK.
generate ✅ → build ✅ → lint ✅ → test ❗

npm install https://pkg.stainless.com/s/stagehand-typescript/cdfe86f437f2ac0ea3f07e55eac1d9437394adb9/dist.tar.gz

✅ stagehand-kotlin studio · code

Your SDK built successfully.
generate ✅ → build ✅ → lint ✅ → test ✅

✅ stagehand-java studio · code

Your SDK built successfully.
generate ✅ → build ✅ → lint ✅ → test ✅

Add the following URL as a Maven source: 'https://pkg.stainless.com/s/stagehand-java/27c666d0fac5476a88e443543b37464bd0097dc7/mvn'

✅ stagehand-php studio · code

Your SDK built successfully.
generate ✅ → lint ✅ → test ✅

✅ stagehand-ruby studio · code

Your SDK built successfully.
generate ✅ → lint ✅ → test ✅

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-02-04 23:58:06 UTC

[cubic-dev-ai]

No issues found across 2 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant CI as Developer/CI
    participant Script as gen-openapi.ts
    participant App as Fastify Server
    participant FS as File System (openapi.v3.yaml)
    participant Mint as Mintlify Docs

    Note over CI,Mint: OpenAPI Specification Generation & Validation Flow

    CI->>Script: Run generation script
    Script->>App: app.ready()
    App-->>Script: Server initialized
    
    Script->>App: app.swagger({ yaml: true })
    App-->>Script: Return raw YAML string
    
    Note right of Script: CHANGED: Post-process YAML string<br/>Apply regex to quote version fields
    Script->>Script: NEW: .replace() openapi: 3.1.0 -> "3.1.0"
    Script->>Script: NEW: .replace() version: 3.1.0 -> "3.1.0"
    
    Script->>FS: writeFile(OUTPUT_PATH, fixedYaml)
    FS-->>Script: Write successful
    Script->>App: app.close()
    
    Note over FS,Mint: Documentation Deployment
    
    Mint->>FS: Load openapi.v3.yaml
    alt Validation Logic
        Mint->>Mint: Validate 'openapi' is string
        Mint->>Mint: Validate 'info.version' is string
        Mint-->>CI: Success: Docs Deployed
    else Validation Failure (Old Behavior)
        Mint-->>CI: Error: Bare numbers found
    end

Loading

[greptile-apps]

Greptile Overview

Greptile Summary

This PR updates the generated OpenAPI v3 YAML to quote openapi and info.version as strings (Mintlify requires these fields to be strings). It also updates the gen-openapi.ts generator to post-process the YAML output with regex replacements before writing packages/server/openapi.v3.yaml.

Overall this fits cleanly into the existing generation flow (Fastify + fastify-zod-openapi + fastify-swagger), but the current regex-based fix is brittle if version formatting changes (e.g. prerelease tags).

Confidence Score: 4/5

• This PR is likely safe to merge after making the version-quoting step robust to non-numeric versions.
• Changes are small and localized, but the current regex only handles purely numeric versions and can silently stop applying if version strings include prerelease/build metadata.
• packages/server/scripts/gen-openapi.ts

Important Files Changed

Filename	Overview
packages/server/scripts/gen-openapi.ts	Post-processes generated OpenAPI YAML to quote openapi and info.version fields for Mintlify validation via regex replacements.
packages/server/openapi.v3.yaml	Quotes top-level openapi and info.version values as strings (e.g., "3.1.0") to satisfy Mintlify validation.

Sequence Diagram

sequenceDiagram
  participant Dev as Developer/CI
  participant Gen as gen-openapi.ts
  participant App as Fastify app
  participant Sw as @fastify/swagger
  participant FS as openapi.v3.yaml

  Dev->>Gen: Run OpenAPI generation script
  Gen->>App: Register routes + zod-openapi components
  Gen->>Sw: app.swagger({ yaml: true })
  Sw-->>Gen: YAML string (may contain unquoted numeric versions)
  Gen->>Gen: Regex-replace openapi + info.version to quoted strings
  Gen->>FS: writeFile(fixedYaml)
  FS-->>Dev: Mintlify validates YAML successfully

Loading

[greptile-apps]

_{2 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}