[sentry-junior]

First, report-only step for #131073. Nothing compared what a public endpoint returns with what its schema says, so an undocumented 402/409 like the one fixed in #131067 went unnoticed.

APITestCase.get_response, and with it get_success_response and get_error_response, now compares each response from a PUBLIC method with tests/apidocs/openapi-derefed.json. The resolved route maps to its schema path through the enumerator the schema build uses, so aliases such as groups/issues resolve to the documented path. It reports two kinds of mismatch:

• undocumented-status: the status isn't a key in the operation's responses. Undocumented 5xx statuses are ignored.
• body-mismatch: the status documents a JSON body and the response doesn't match it. A status documented without a body, such as RESPONSE_NOT_FOUND, only has its status compared.

Each process loads the schema once with orjson, without building an openapi_core Spec, and caches one validator per operation and status. xdist workers send their findings to the controller, which prints a summary and writes .artifacts/api-response-schema.json. Without a readable schema it prints one line and skips the comparison. Public operations missing from the schema are counted, since that usually means the schema is stale.

SENTRY_API_RESPONSE_SCHEMA sets the mode: report (default) only summarizes, strict fails a test on a mismatch that isn't in tests/apidocs/response-schema-baseline.txt, update adds new mismatches to that baseline, and off disables it. Nothing fails by default. "Responses seen in tests" in src/sentry/apidocs/README.md describes it.

Rollout: report-only (this PR) → build the schema in backend CI and complete the baseline → strict in CI as a ratchet → prune the baseline as endpoints are fixed.

Open questions:

• Backend CI doesn't build openapi-derefed.json yet. Should it build the schema before the backend tests, or download it as an artifact?
• Should the hook move from get_response to the test client, so that tests calling self.client directly are compared too?
• PUBLIC_EXPERIMENTAL operations are published but not compared yet. Include them?

Refs #131073

via @BYK.

--

View Session [Sentry]

[cursor]

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 1e61f13. Configure here.}