[sentry-junior]

Stacked on #130518 (which is stacked on #130472). This adds the data sentry-docs needs to build the API reference from the @sentry/api version it pins, so it no longer has to read openapi-derefed.json from a pinned sentry-api-schema commit. The sentry-docs adapter is a separate PR in getsentry/sentry-docs.

What it adds

• scripts/generate-docs.mjs, next to the operations generator. It runs lib/docs-catalog.mjs extractDocs(spec) on the release's original dereferenced spec and emits src/docs.ts. That file holds { tags, operations } as a JSON string literal, so tsc doesn't infer a type for 3.7 MB of data, and it ships as @sentry/api/docs (dist/docs.js plus .d.ts).
• Shape (lib/docs-types.ts):
  • tags: name, description, sidebarName (x-sidebar-name) and displayDescription (x-display-description).
  • operations, in spec order: operationId, method, path, and summary and description copied as written. Also tags, deprecated, experimental (x-sentry-experimental), server URLs, security requirements, and parameters (path-level merged with operation overrides) with in, required, description, experimental and schema. The request body comes from its first content type (content type, required, schema, example), and every response has its status, description, content type, schema and example/examples.
• extractDocs is exported too, so sentry-docs' OPENAPI_LOCAL_PATH preview of an unreleased local spec goes through the same projection as the published data.
• lib/http-methods.mjs holds the HTTP method set that both catalogs use.

The export's shape is now a semver contract

sentry-docs, and anything else that imports @sentry/api/docs, depends on these field names and types. Removing or renaming a field, or changing its type, is a major release. Adding fields is a minor release. The README says so.

Size

Measured with pnpm pack against #130518, built from the same spec:

	tgz	unpacked	files
#130518	3,417,315 B	34,077,476 B	79
this PR	3,876,230 B	37,818,818 B	82
change	+459 KB (+13%)	+3.74 MB (+11%)	+3

Almost all of it is dist/docs.js (3,736,140 B). It's a separate entry point, so @sentry/api and @sentry/api/client users like toolkit don't load it unless they import ./docs. They only pay for the download.

Tests

• test/docs.test.ts:
  • A fixture test pins the exact output shape. It covers path-level parameter overrides, experimental flags, multiple content types, responses without content, named examples, servers and security.
  • Drift tests compare the published @sentry/api/docs to the spec in spec/openapi-derefed.json:
    • the export equals extractDocs(spec);
    • tag and operation order matches the spec;
    • for every operation, the text, parameters, request schema and example, and response schemas and examples match the spec directly.
• test/package.test.ts: the packed-tarball smoke test imports @sentry/api/docs.

Checks

• build, typecheck (tsc6 test and browser configs) and test:vitest all pass locally: 53 files, 661 tests. knip is clean.
• I fed a locally packed tarball to sentry-docs. Its API reference data from @sentry/api/docs is byte-identical to its current spec reader's output on the same spec, apart from required: false vs. absent on optional query params, which renders the same. The rendered <main> HTML is identical on 5 API pages. Details and screenshots are in the sentry-docs PR.
• No UI change in sentry. This only touches static/packages/api/.

Merge order

This PR, then publishing an @sentry/api version with ./docs through the normal release, then the sentry-docs PR, whose dependency bump is its last step.

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

via @BYK.

--

View Session in Sentry

[sentry]

Sentry Snapshot Testing

Name	Added	Removed	Changed	Renamed	Unchanged	Skipped	Status
sentry-frontend sentry-frontend	0	0	0	0	824	0	✅ Unchanged

⚙️ sentry-frontend Snapshot Settings

[sentry-junior]

Moved to getsentry/sentry-api-schema#150.