为 Sentry API 端点补全 OpenAPI…

当需要为 Sentry 端点编写或修复 drf-spectacular 的 @extend_schema 文档、声明响应 TypedDict、标注请求参数、修正声明类型与运行时响应不一致、迁移旧版 api-docs 路径或将端点提升为 PUBLIC 时使用。

适用场景

解决思路

1. 先确认服务该路由的端点类及其行为，通常用调用它的 MCP 工具最快确认。
2. 在类级别添加 @extend_schema(tags=[...])，使用最接近的现有 OPENAPI_TAGS 条目。
3. 在方法级别添加 @extend_schema(operation_id=..., parameters=[...], responses={...}, examples=...)。
4. 复用 src/sentry/apidocs/parameters.py 和 examples/*.py，并确保设置 owner = ApiOwner.<TEAM>。
5. 如果存在覆盖该路径的旧版 api-docs/paths/**/*.json，将其删除（见旧版迁移要点）。
6. 用真实 token 请求线上端点，将返回的键与类型和 TypedDict 逐项对比（序列化器有时不准确）：注意计数返回 float 而非 int、声明为 int 的 ID 实际为字符串、嵌套类型字段数量不符等，按运行时结果修正声明类型，例如：curl -s -H "Authorization: Bearer $TOKEN" "https://us.sentry.io/api/0/<endpoint>" | jq 'keys'。
7. 复用规范响应类型：遵循代码库的 XxxResponseOptional(TypedDict, total=False) mixin 模式（主类声明必需字段）；区分可空与缺失——T | None 表示键始终存在但值可为 null，NotRequired[T] 表示键仅在特定条件下设置（如 expand 查询参数）；优先复用已有规范类型，不要在 *_types.py 中重复声明第二、第三份副本；若没有可复用的规范类型（如来自 vroom/profiling 等其他服务的代理载荷），用 dict[str, Any] 标注，并从拥有该服务的仓库确认结构，而不仅看序列化器。
8. 当序列化器返回基类型加额外字段时，重构产出代码使响应类型可被推断，避免使用 cast 和 # type: ignore。
9. 旧版文档迁移按路径全有或全无：删除 api-docs/paths/**/*.json 文件及其在 api-docs/openapi.json 中的 $ref；由于 drf-spectacular 的 APPEND_PATHS 不会合并 HTTP 方法，一旦路径上任一方法使用 @extend_schema，该路径上所有旧版方法都会消失，因此必须在一次提交中迁移该路径上的所有方法。
10. 提升为 PUBLIC 时仅针对具体端点（同级端点保持 PRIVATE）：将 publish_status[<METHOD>] 提升为 PUBLIC 并设置 owner = ApiOwner.<TEAM>；在同一次变更中从 API_OWNERSHIP_ALLOWLIST_DONT_MODIFY 移除该方法；若端点冗余或正在重命名，先在独立变更中删除或弃用旧版本，再在其上叠加发布变更；若权限范围扩大（如 event:read → event:{admin,read,write}），在 PR 中说明这只是 drf-spectacular 依据 permission_classes 重新生成、仅文档层面变化。
11. 注意变更需等 sentry-api-schema 下游重新生成后才会到达 @sentry/api SDK / MCP。
12. 执行验证：make build-api-docs；pnpm run validate-api-examples；.venv/bin/pytest -q --reuse-db tests/apidocs/endpoints/<area>/test_<name>.py；.venv/bin/prek run -q --files <changed paths>。

适用边界 · 注意事项

• 不适用于非 Sentry 项目或未使用 drf-spectacular 的代码库。
• 不要为代理自其他服务的载荷凭空发明镜像类型，应使用 dict[str, Any] 并向拥有方仓库确认结构。
• 不要用 cast 或 # type: ignore 强行压制类型，应重构产出代码使类型可推断。