feat(api-docs): Build the API reference from @sentry/api/docs - #20679

The API reference now comes from the @sentry/api version this repo pins. It no longer fetches openapi-derefed.json from a pinned getsentry/sentry-api-schema commit; @sentry/api now builds in getsentry/sentry (static/packages/api).

Changes

• src/build/resolveOpenAPI.ts reads {tags, operations} from @sentry/api/docs and maps them to the same APICategory/API shapes the pages already use.
  • OPENAPI_LOCAL_PATH still works in development. It reads a local make build-api-docs spec and runs it through the package's extractDocs(), so previews take the same path as production.
  • src/build/open-api/types.ts is gone. The package types replace it.
• Bump workflow: bump-api-schema-sha.yml is now Bump @sentry/api.
  • It runs hourly and on workflow_dispatch, with a concurrency group so the two can't push the same branch.
  • scripts/bump-sentry-api.sh reads the latest version with npm view, runs pnpm add --save-exact --lockfile-only, then opens and merges the PR with the same app token as before.
  • The file keeps its name so existing dispatches still reach it.
  • Dependabot here only does security updates, so it doesn't fit.
  • The script is POSIX sh, passes shellcheck --shell=sh --enable=check-extra-masked-returns, and has a pre-commit hook scoped to it.
• develop-docs/backend/api/public.mdx: the build process section describes the new flow, and the openapi-diff text matches ci(openapi-diff): Compare API schemas with the PR's merge-base sentry#130541: a changelog that never fails, plus a separate RPC breaking-change job. Hold that part until that PR merges.

Verification

All of this ran with a locally packed @sentry/api tarball from that PR. Nothing was published.

• Page data: I dumped apiCategories() from the old reader and the new adapter on the same spec. The output has 23 categories and 285 APIs, and is identical except that optional query parameters now have required: false where the key used to be missing (494 parameters). The pages check !!param.required, so they render the same. Production data and the OPENAPI_LOCAL_PATH path give byte-identical output.
• HTML: the rendered <main> is byte-identical on /api/users/list-your-organizations/, /api/teams/create-a-new-team/, /api/projects/create-a-custom-inbound-filter/ (an experimental endpoint with a body), /api/teams/ and /api/events/retrieve-an-issue/.
• pnpm lint:ts, vitest run src/build/resolveOpenAPI.spec.ts and eslint all pass.
• The bump script ran under dash with stubbed npm, pnpm, git and gh. Same version: it skips. Newer: it runs the full flow. A non-version answer from npm or any failing command: it exits non-zero. pnpm add --lockfile-only ran for real against a copy of this repo's manifest and lockfile.

Screenshots

These are next dev screenshots at 1400px wide. Before is the current reader on the same spec through OPENAPI_LOCAL_PATH; after is this PR reading @sentry/api/docs. The images are pixel-identical except for the Next.js dev badge, so two pairs have the same URL.

Create a New Team

Before	After

Create a Custom Inbound Filter (experimental, with a body)

Before	After

List Your Organizations

Before	After

Merge order

1. feat(api): Export API reference data as @sentry/api/docs sentry#130538 merges and an @sentry/api version with ./docs is released.
2. Bump the pin in this PR to that version.
3. Merge this PR.
4. Afterwards, sentry-api-schema's "Cascade to sentry-docs" dispatch is no longer needed.

Co-Authored-By: BYK 126780+BYK@users.noreply.github.com

via @BYK.

--

View Session in Sentry