Repository navigation
feat(api-docs): Build the API reference from @sentry/api/docs - #20679
Open
sentry-junior[bot] wants to merge 21 commits into
Open
sentry-junior[bot] wants to merge 21 commits into
sentry-junior[bot] wants to merge 21 commits into
Conversation
Read the API reference data from the pinned @sentry/api package instead of fetching openapi-derefed.json from a pinned sentry-api-schema commit. OPENAPI_LOCAL_PATH still previews a local spec, through the package's extractDocs(). Replace the API Schema SHA bump with a @sentry/api version bump that runs hourly and on dispatch. Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
github-actions
Bot
added
the
Priority: Needs Triage
Contributor
|
Please update the IS YOUR CHANGE URGENT? section of the PR description:
This information helps the Docs team prioritize your review. |
Contributor
|
Getting ready to monitor this change · Rollout details
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>
…sentry-api # Conflicts: # src/build/resolveOpenAPI.ts
…sentry-api # Conflicts: # src/build/resolveOpenAPI.ts
The workflow no longer depends on the script's executable bit.
…sentry-api # Conflicts: # src/build/resolveOpenAPI.ts
Contributor
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit a4fb800. Configure here.
A run that stops before the merge leaves the bump branch and maybe its PR behind. Force-push the branch and reuse an open PR so the next run can finish instead of failing.
…sentry-api # Conflicts: # src/build/resolveOpenAPI.ts
…sentry-api # Conflicts: # src/build/resolveOpenAPI.ts
…sentry-api # Conflicts: # src/build/resolveOpenAPI.ts
…sentry-api # Conflicts: # src/build/resolveOpenAPI.ts
Keep the deletion of src/build/open-api/types.ts and the @sentry/api/docs reader, and carry master's full-path display (#20787) over to it: API paths now get the docs data's apiBasePath prepended. apiLocation and its tests are dropped, because @sentry/api/docs already splits the base path out of the server URLs.
…sentry-api # Conflicts: # src/build/resolveOpenAPI.ts
BYK
added a commit
to getsentry/sentry-api-schema
that referenced
this pull request
Nov 13, 2026
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 `path`s 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> <!-- junior-session-footer:start --> <!-- junior-conversation-id:agent%3A69da19b385017e68b7f9eace56e9477f --> -- [View Session](https://junior-prod.sentry.dev/conversations/agent%3A69da19b385017e68b7f9eace56e9477f) [[Sentry]](https://sentry.sentry.io/explore/conversations/agent%3A69da19b385017e68b7f9eace56e9477f/?project=4510944073809921) <!-- junior-session-footer:end --> --------- Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com> Co-authored-by: BYK <126780+BYK@users.noreply.github.com>
…sentry-api # Conflicts: # src/build/resolveOpenAPI.ts
…sentry-api # Conflicts: # src/build/resolveOpenAPI.ts
…sentry-api # Conflicts: # src/build/resolveOpenAPI.ts
2.1.0 is the first release that exports @sentry/api/docs.
@sentry/api only declares an "import" condition for ./docs, so scripts/algolia.ts, which tsx loads through Node's CJS resolver, failed with ERR_PACKAGE_PATH_NOT_EXPORTED. Alias it to its dist file, as scripts/tsconfig.json already does for rehype-prism-diff.
…sentry-api # Conflicts: # src/build/resolveOpenAPI.ts
…sentry-api # Conflicts: # src/build/resolveOpenAPI.ts
…sentry-api # Conflicts: # src/build/resolveOpenAPI.ts
This branch had an error being deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The API reference now comes from the
@sentry/apiversion this repo pins. It no longer fetchesopenapi-derefed.jsonfrom a pinned getsentry/sentry-api-schema commit;@sentry/apinow builds in getsentry/sentry (static/packages/api).Important
Don't merge until an
@sentry/apirelease with the./docsexport is on npm. That export comes from getsentry/sentry#130538. This PR pins1.58.0, the latest version today, which doesn't have./docsyet, so the build fails until the pin moves. The last step before merging is to run Bump @sentry/api (orpnpm add -E @sentry/api@<first version with ./docs>).Changes
src/build/resolveOpenAPI.tsreads{tags, operations}from@sentry/api/docsand maps them to the sameAPICategory/APIshapes the pages already use.OPENAPI_LOCAL_PATHstill works in development. It reads a localmake build-api-docsspec and runs it through the package'sextractDocs(), so previews take the same path as production.src/build/open-api/types.tsis gone. The package types replace it.bump-api-schema-sha.ymlis now Bump @sentry/api.workflow_dispatch, with a concurrency group so the two can't push the same branch.scripts/bump-sentry-api.shreads the latest version withnpm view, runspnpm add --save-exact --lockfile-only, then opens and merges the PR with the same app token as before.sh, passesshellcheck --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 theopenapi-difftext 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/apitarball from that PR. Nothing was published.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 haverequired: falsewhere the key used to be missing (494 parameters). The pages check!!param.required, so they render the same. Production data and theOPENAPI_LOCAL_PATHpath give byte-identical output.<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.tsand eslint all pass.npm,pnpm,gitandgh. 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-onlyran for real against a copy of this repo's manifest and lockfile.Screenshots
These are
next devscreenshots at 1400px wide. Before is the current reader on the same spec throughOPENAPI_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
Create a Custom Inbound Filter (experimental, with a body)
List Your Organizations
Merge order
@sentry/apiversion with./docsis released.Co-Authored-By: BYK 126780+BYK@users.noreply.github.com
via @BYK.
--
View Session in Sentry