[sentry-junior]

Stacked on #149. Ported from getsentry/sentry#130538, per @BYK's request there: get the docs aligned here first, then move @sentry/api into getsentry/sentry.

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 commit of this repository. The sentry-docs adapter is getsentry/sentry-docs#20679.

Changes from the sentry version

2.0.0 (#148) made every path relative to the API base path and trimmed server URLs to their origin. The export now follows the same contract:

• operation paths are relative, such as /organizations/, the same as @sentry/api/operations;
• the base path ships as API_BASE_PATH (/api/0) and as apiBasePath in extractDocs() output, so a page builds the full path as ${API_BASE_PATH}${operation.path};
• per-operation servers are origins.

extractDocs() applies splitApiBasePath to a copy of the spec it gets, so the published data and a preview of a local spec have the same shape. It accepts both the current spec and one that declares the base path in servers.

sentry-docs#20679 needs a follow-up for this: its adapter has to prepend API_BASE_PATH to paths, like sentry-docs#20787 does for 2.0.0. I'll push that once this shape is settled.

What it adds

• scripts/generate-docs.mjs, next to the operations generator. It runs lib/docs-catalog.mjs extractDocs(spec) on the original openapi-derefed.json and emits src/docs.ts. That file holds the data as a JSON string literal, so tsc doesn't infer a type for 3.7 MB of data. It ships as @sentry/api/docs (dist/docs.js plus .d.ts).
• Shape (lib/docs-types.ts):
  • apiBasePath / API_BASE_PATH.
  • tags: name, description, sidebarName (x-sidebar-name) and displayDescription (x-display-description).
  • operations, in spec order: operationId, method and relative path, with summary and description copied as written. Also tags, deprecated, experimental (x-sentry-experimental), server origins, 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 npm pack --dry-run from clean builds of #149 and this branch, using the spec in this repository:

	tgz	unpacked	files
#149	3,385,825 B	35,812,862 B	80
this PR	3,828,867 B	39,660,930 B	86
change	+443 KB (+13%)	+3.85 MB (+11%)	+6

Almost all of it is dist/docs.js (3,840,561 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. Its spec declares /api/0 in servers and an operation server override under it, so the test also covers the relative paths, apiBasePath and origin-only servers. It also covers path-level parameter overrides, experimental flags, multiple content types, responses without content, named examples and security.
  • Drift tests compare the published @sentry/api/docs with openapi-derefed.json:
    • the export equals extractDocs(spec), and API_BASE_PATH is /api/0;
    • tag and operation order matches the spec, with API_BASE_PATH plus each relative path equal to the spec's path;
    • 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.

pnpm build, pnpm typecheck and pnpm test pass locally (54 files, 679 tests).

No UI change here. The sentry-docs PR carries the API reference screenshots.

Merge order

#149, this PR, the normal release of an @sentry/api version with ./docs, then getsentry/sentry-docs#20679 with its API_BASE_PATH follow-up. That PR's dependency bump is its last step.

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

--

View Session [Sentry]