API reference: auto-generate from OpenAPI specs, add v1 and v2

[gaprl]

Context

Since the Mintlify migration (#2634), the API reference has been a frozen snapshot: the checked-in public_v1.openapi.yaml was never refreshed, and every endpoint needed a hand-generated MDX stub plus a docs.json nav entry. Endpoints added to the API since May 28 (e.g. ticket link/unlink) never appeared in the docs. Support flagged this.

Before the migration this was self-updating: the docs site linked out to semgrep.dev/api/v1/docs, which ReDoc renders live from the backend's own spec.

Refs APPEX-1187.

What

1. Auto-generated API pages. The API tab in docs.json now points at the specs via Mintlify's openapi navigation field. All per-endpoint MDX stubs and per-service overview pages are deleted; Mintlify generates a page per operation, grouped by OpenAPI tag. New endpoints in the spec show up in the docs with no manual work.
2. v2 API reference added, with a version switcher. public_v2.openapi.yaml (from semgrep.dev/api/v2/openapi.yaml, 214 operations) renders at /api-reference/v2/... (v1 and v2 share tag names, so v2 generates into its own directory). The API tab uses Mintlify dropdowns as a v1 / v2 (Experimental) version switcher at the top of the sidebar — one version's services shown at a time, which keeps the sidebar short (v2 alone has ~40 services). Global anchors (Registry/Playground/Academy) are untouched. v2 gets its own Overview pages (Introduction with maturity-level badges, Authentication, Terms of Use), derived from the v2 spec's info.description.
3. v1 spec refreshed now — picks up ~670 lines of drift including the new POST /deployments/{deploymentId}/tickets/link and /tickets/unlink endpoints.

URL compatibility

• v1 and v2 pages live under symmetric paths: /api-reference/v1/... and /api-reference/v2/....
• All historical v1 URLs (/api-reference/<service>/<endpoint>, plus Introduction/Authentication/Terms-of-Use) 307-redirect to their /v1/-prefixed equivalents via per-service :slug* wildcard redirects. Endpoint slugs themselves are unchanged (auto-generated slugs match the old scraped ones — verified by probing a local mintlify dev build).
• One slug genuinely changed: the findings endpoint summary was renamed upstream, so an exact redirect maps the old .../list-code-or-supply-chain-findings URL to .../list-code-supply-chain-or-ai-powered-scan-findings. Internal links were updated everywhere.
• The deleted per-service overview pages (/api-reference/TicketingService etc.) got redirects to a representative endpoint in their group.

Upstream spec bugs found (fix to follow in semgrep-app)

Mintlify validates specs strictly (ReDoc doesn't) and caught real bugs in the live specs, patched here in the checked-in copies:

• v1: type: bool instead of boolean (2×, is_malicious)
• v2: duplicate tags entries (AutomationsService, ProjectsService)
• v2: type: Array of strings <int64> prose in the TeamCreate.repositoryIds type field

These need fixing at the source, or the scheduled refresh (stacked PR #2706) will re-import them and its validate step will block the update. A follow-up semgrep-app PR will fix these and point /api/v1/docs + /api/v2/docs at these Mintlify pages.

Verification

• npx mintlify validate (from docs/): build validation passed
• npx mintlify broken-links --check-redirects (what Docs CI runs): no broken links found
• Probed generated pages on a local mintlify dev server: old v1 slugs return 200 (incl. the [beta]-... bracket URL), v2 pages render at /api-reference/v2/<service>/<operation>, new ticket link/unlink endpoints have pages.

Nav group labels

Mintlify labels auto-generated groups with the raw tag name (DeploymentsService) and ignores ReDoc's x-displayName extension, which both specs already carry. Mintlify's equivalent is x-group, so the specs here mirror x-displayName into x-group (restores the familiar labels: "Deployment", "Supply Chain", …), and the refresh workflow (stacked PR #2706) applies the same one-line transform after fetching so the labels survive cron refreshes. Once semgrep-app emits x-group natively, the transform step can be deleted.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
semgrep-docs	🟢 Ready	View Preview	Jul 13, 2026, 6:10 PM

[khorne3]

Thank you!