mcpField
D
document-api-endpoint

document-api-endpoint

github.com/getsentry开发1.1k1.2k 次安装5 天前更新
代码仓库

关于 document-api-endpoint

用于在 Sentry 代码库中使用 drf-spectacular 编写 API 端点文档和类型的技能。重点是让声明的架构与运行时响应一致，并安全迁移旧文档。

主要功能

  1. 01添加类级和方法级架构装饰器
  2. 02复用规范响应类型和示例
  3. 03对照实时端点响应检查类型
  4. 04完整迁移旧路径文档
  5. 05验证生成的 API 文档

适用场景

  1. 01为新的 Sentry API 端点编写文档
  2. 02修正与运行时不符的响应类型
  3. 03将端点升级为 PUBLIC

MCP 相关

该技能指出，可通过调用端点的 MCP 工具检查其行为；还说明重新生成的 `sentry-api-schema` 如何传递到 SDK 和 MCP。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/getsentry/skills --skill document-api-endpoint

安装后在 Claude Code 中输入/document-api-endpoint确认已加载。

详细介绍

编写文档并为 Sentry API 端点添加类型

使用 drf-spectacular 为 Sentry 端点添加或修正文档。完整参考资料见 https://develop.sentry.dev/backend/api/public/，其中对你最有用的是 https://develop.sentry.dev/backend/api/public/#5-method-decorator。本指南补充了其中不那么显而易见的经验。大部分工作是让声明的架构与端点实际返回的内容相符。编写文档前，先确定处理该路由的端点类及其作用；调用该端点的 MCP 工具通常是确认其行为最快的方法。将 PRIVATE/EXPERIMENTAL 端点提升为 PUBLIC 是一种应用场景（见下文）。

工作流

  1. 类级别的 @extend_schema(tags=[...]) —— 使用最接近的现有 OPENAPI_TAGS 条目。
  2. 方法级别的 @extend_schema(operation_id=..., parameters=[...], responses={...}, examples=...)。
  3. 复用 src/sentry/apidocs/parameters.py 和 examples/*.py；确保已设置 owner = ApiOwner.<TEAM>。
  4. 如果旧版 api-docs/paths/**/*.json 涵盖了该路径，请将其删除（见经验 4）。
  5. 验证，然后对照线上端点核实（见经验 1）。

经验

1. 仔细比较代码的实际行为与声明的类型

理想情况下，使用真实令牌调用线上端点，并将返回的键和类型与 TypedDict 逐一比对。序列化器有时并不准确。注意计数是否以浮点数而非整数返回、声明为 int 的 ID 是否以字符串形式输出，以及嵌套类型声明的字段数量是否有误。修正声明的类型，使之与运行时一致。

curl -s -H "Authorization: Bearer $TOKEN" "https://us.sentry.io/api/0/<endpoint>" | jq 'keys'
2. 复用规范的响应类型

匹配代码库中的 XxxResponseOptional(TypedDict, total=False) 混入类型（主类声明必需字段）。可为 null 与可缺省的区别：T | None = 键始终存在，值可能为 null；NotRequired[T] = 仅在特定条件下设置该键（例如 expand 查询参数）。复用现有的规范类型，而不是在 *_types.py 中重新声明第二或第三份副本。如果没有合适的规范类型可复用（例如，从 vroom/profiling 等其他服务代理过来的负载），请将其类型设为 dict[str, Any]，而不是凭空新建一个镜像类型，并从所属服务的代码库确认其结构，不要只依赖序列化器。

3. 推断类型。避免使用 cast 和 # type: ignore

当序列化器返回基础类型及额外字段时，重构生成响应的代码，让响应类型能够被推断出来，而不是强行指定。

4. 旧版文档迁移必须针对每条路径一次性完成

删除 api-docs/paths/**/*.json 文件及其在 api-docs/openapi.json 中的 $ref。drf-spectacular 的 APPEND_PATHS 不会合并 HTTP 方法，因此一旦某条路径上的任一方法使用了 @extend_schema，该路径上的所有旧版方法都会消失——请在同一次提交中迁移该路径上的每个方法。

提升为 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 重新生成的结果，仅涉及文档。

只有在 sentry-api-schema 向下游重新生成后，该变更才会影响 @sentry/api SDK / MCP。

验证

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>

评论

支持 Markdown