[billyvg]

Why?

#129315 types apiOptions responses from contracts generated from the backend. This pulls out the generator that writes static/app/utils/api/apiContracts.generated.ts, so it can be reviewed apart from the frontend changes.

Stacked on the PR below, which builds the internal spec this reads:

• feat(apidocs): Build an internal OpenAPI spec of every endpoint method #129559

How?

make build-api-contracts runs make build-internal-api-docs, then tools/api_contracts_to_typescript.py, then oxfmt. The script writes:

• one TypeScript type per component schema in the internal spec
• <OperationId>Response for each success body that isn't a bare component reference, such as the ones the legacy api-docs JSON declares inline
• <Property>Enum for each enum of two or more members that types properties in more than one place, such as the 598 timezones three types share, so it's declared once
• ApiMapping, from each KnownSentryApiUrls route to {response: T} for each method that declares a success body, with a comment giving the operation and its publish status. T is always a type name.

Routes the frontend can't name are skipped. A route spelled with a literal alternation, such as (?:issues|groups), is mapped under every path in x-sentry-path-aliases. Where a path is spelled directly and also reached as another route's alias, the direct spelling wins.

Decisions

• An undeclared response is left out, not typed unknown. Responses marked x-sentry-undocumented, and ones with no body, get no ApiMapping entry, so they don't look like contracts. A type hint the build couldn't resolve (x-sentry-unresolved) does become unknown, since the rest of its schema is still useful.
• The script doesn't import Django. It spells out the x-sentry-* extension names itself. A test in tests/sentry/apidocs/internal/test_generator.py checks they match the names the internal build writes.
• Enums are hoisted here, not by drf-spectacular's postprocess_schema_enums. Turned on for the internal build, that hook walks only a component's top-level properties, so most repeated enums stay inline. It also compares choice labels as well as values, so the timezones still came out as two 598-member enums. And it names collisions with a hash of the choices (Status42cEnum), which changes whenever the choices do. Here, as in that hook, a blank or null member stays at the use site (TimezoneEnum | ''). Enums that would share a name are each qualified by the first type that has them (GroupDetailsResponseStatusEnum).
• The output already passes lint. Object keys are ordered required-first and then by name, to satisfy @sentry/sort-interface-keys. Arrays are T[] or Array<T> as typescript/array-type requires, and enum literals are sorted so the output doesn't change between builds.

Not in this PR: the generated file, the CI job that regenerates and commits it, the knip entry, apiExamples.generated.ts, and apiOptions.contract(). Until #129568 lands, make build-api-contracts fails at the internal spec's --validate step on the csrf endpoint.

🤖 Generated with Claude Code

[linear-code]

ENG-8961