跳到主内容
智客 ZICQ

技能库 智客分类:文档办公 document-api-endpoint

Document Api Endpoint

文档和键入 Sentry API 端点 。 写入或修复 @extend_schema 装饰器,指定响应 TypedDicts,类型请求参数,正确的类型漂移在宣布的chema和运行时间响应之间,并验证生成的光谱. 当被请求用于"文档一个端点","添加OpenAPI docs","添加/fix@extend_schema","键入一个端点响应","固定类型漂移","重新使用一个响应类型","切出一个超载端点","具体说明响应计划","添加一个TypedDict响应","插入一个遗留的API-docs路径","固定一个参数类型","使一个端点公开"/"促进一个端点"(此处的促进是一节).

710 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

文档和键入 Sentry API 端点 。 写入或修补 @extend_schema 装饰器, 指定响应 TypedDicts, 类型请求参数, 正确的类型漂移在声明的chema 和运行时响应之间, 并验证生成的光谱

何时用

请求“文档端点”、“添加 OpenAPI docs”、“添加/fix @extend_schema”、“键入一个端点响应”、“键入一个响应类型”、“固定类型漂移”、“重用一个响应类型”、“切出一个超载端点”、“请具体说明响应计划”、“添加一个 TypedDict响应”、“移出一个 le

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Document & Type a Sentry API Endpoint、Workflow、Lessons、1. Carefully compare what the code does vs declared types、2. Reuse the canonical response type、3. Infer the type. Avoid `cast` and `# type: ignore`。 其中含规范建议的小节:分步指令。

文件分析

文件分析:这是一份仅含 SKILL.md 的指令型技能,代理激活后整份正文进入上下文。

官方 description(原文)

Document and type a Sentry API endpoint. Write or fix @extend_schema decorators, specify response TypedDicts, type request parameters, correct type drift between the declared schema and the runtime response, and validate the generated spec. Use when asked to "document an endpoint", "add OpenAPI docs", "add/fix @extend_schema", "type an endpoint response", "fix the response type", "fix type drift", "reuse a response type", "split an overloaded endpoint", "specify the response schema", "add a TypedDict response", "migrate a legacy api-docs path", "fix a parameter type", or "make an endpoint public" / "promote an endpoint" (promotion is one section here).

Document & Type a Sentry API EndpointWorkflowLessons1. Carefully compare what the code does vs declared types2. Reuse the canonical response type3. Infer the type. Avoid `cast` and `# type: ignore`4. Legacy doc migration is all-or-nothing per pathPromoting to PUBLICValidate

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
document-api-endpoint
description
Document and type a Sentry API endpoint. Write or fix @extend_schema decorators, specify response TypedDicts, type request parameters, correct type drift between the declared schema and the runtime response, and validate the generated spec. Use when asked to "document an endpoint", "add OpenAPI docs", "add/fix @extend_schema", "type an endpoint response", "fix the response type", "fix type drift", "reuse a response type", "split an overloaded endpoint", "specify the response schema", "add a TypedDict response", "migrate a legacy api-docs path", "fix a parameter type", or "make an endpoint public" / "promote an endpoint" (promotion is one section here).
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「document-api-endpoint」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-81e64a5cce37f651-%E6%96%87%E6%A1%A3-Api-%E7%BB%93%E6%9D%9F%E7%82%B9.html
请存为 .cursor/skills/document-api-endpoint/SKILL.md 或 .claude/skills/document-api-endpoint/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/getsentry/skills' --list

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

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: document-api-endpoint description: Document and type a Sentry API endpoint. Write or fix @extend_schema decorators, specify response TypedDicts, type request parameters, correct type drift between the declared schema and the runtime response, and validate the generated spec. Use when asked to "document an endpoint", "add OpenAPI docs", "add/fix @extend_schema", "type an endpoint response", "fix the response type", "fix type drift", "reuse a response type", "split an overloaded endpoint", "specify the response schema", "add a TypedDict response", "migrate a legacy api-docs path", "fix a parameter type", or "make an endpoint public" / "promote an endpoint" (promotion is one section here). --- # Document & Type a Sentry API Endpoint Add or fix OpenAPI docs for a Sentry endpoint with drf-spectacular. Full reference is at https://develop.sentry.dev/backend/api/public/, the most useful section to you will be https://develop.sentry.dev/backend/api/public/#5-method-decorator. This skill captures the non-obvious lessons on top of it. Most of the work is making the declared schema match what the endpoint actually returns. Before documenting, identify which endpoint class serves the route and what it does; the MCP tool that calls it is usually the fastest way to confirm its behavior. Promoting a PRIVATE/EXPERIMENTAL endpoint to PUBLIC is one application (see below). ## Workflow 1. Class-level `@extend_schema(tags=[...])` — use the closest existing `OPENAPI_TAGS` entry. 2. Method-level `@extend_schema(operation_id=..., parameters=[...], responses={...}, examples=...)`. 3. Reuse `src/sentry/apidocs/parameters.py` and `examples/*.py`; ensure `owner = ApiOwner.` is set. 4. If a legacy `api-docs/paths/**/*.json` covers the path, remove it (see lesson 4). 5. Validate, then verify against the live endpoint (lesson 1). ## Lessons ### 1. Carefully compare what the code does vs declared types Ideally, hit the live endpoint with a real token and diff the keys and types against your TypedDict. Serializers are sometimes inaccurate. Look out for counts coming back as floats instead of integers, IDs declared `int` emitted as strings, nested types declaring the wrong number of fields. Correct the declared type to match runtime. ```bash curl -s -H "Authorization: Bearer $TOKEN" "https://us.sentry.io/api/0/" | jq 'keys' ``` ### 2. Reuse the canonical response type Match the codebase's `XxxResponseOptional(TypedDict, total=False)` mixin (main class declares required fields). Nullable-vs-absent: `T | None` = key always present, value may be null; `NotRequired[T]` = key only set under a condition (e.g. an `expand` query param). Reuse the existing canonical type instead of re-declaring a second or third copy in a `*_types.py`. If there's no clean canonical type to reuse (e.g. a payload proxied from another service like vroom/profiling), type it `dict[str, Any]` rather than inventing a new mirror, and confirm the shape from the owning service's repo, not just the serializer. ### 3. Infer the type. Avoid `cast` and `# type: ignore` When a serializer returns a base type plus extra fields, refactor the producing code so the response type is inferred rather than forced. ### 4. Legacy doc migration is all-or-nothing per path Delete the `api-docs/paths/**/*.json` file AND its `$ref` in `api-docs/openapi.json`. drf-spectacular's `APPEND_PATHS` does not merge HTTP methods, so once any method on a path uses `@extend_schema`, all *legacy* methods on that path vanish — migrate every method on the path in one commit. ## Promoting to PUBLIC Do the workflow above, then on the concrete endpoint only (leave siblings PRIVATE): - Bump `publish_status[]` → `PUBLIC` and set `owner = ApiOwner.`. - Remove the method from `API_OWNERSHIP_ALLOWLIST_DONT_MODIFY` in the same change as the flip. - If the endpoint is redundant or being renamed, delete or deprecate the old version in its own change first, then stack the publish on top. - Note in the PR if scopes widen (`event:read` → `event:{admin,read,write}`) — that's drf-spectacular regenerating from `permission_classes`, documentation-only. The change reaches the `@sentry/api` SDK / MCP only after `sentry-api-schema` regenerates downstream. ## Validate ```bash make build-api-docs pnpm run validate-api-examples .venv/bin/pytest -q --reuse-db tests/apidocs/endpoints//test_.py .venv/bin/prek run -q --files ```

相关技能

文档办公

Ontology

为结构化的代理内存和可堆肥技能所打入的知识图. 在创建/征服实体(Person, project, Task, Evention, Document)时使用,链接相关对象,强制约束,规划多步动作作为图变,或技能需要共享状态时使用. 触发到"记住","我知道什么","链接X到Y",…

文档办公

Nano Pdf

使用纳米-pdf CLI编辑带有自然语言指令的PDF.

文档办公

Word / DOCX

创建,检查,并编辑有可靠样式的Microsoft Word文档和DOCX文件,编号,跟踪更改,表格,章节,并进行相容性检查. 当 (1) 任务涉及 Word 或 ".docx " 时使用; (2) 文件包括跟踪的更改,评论,字段,表格,模板,或页面布局限制; (3) 文档必须在不…

文档办公

Api Gateway

通过 Maton 网关调用第三方 API, 它为用户已经连接的应用程序注入证书 。 当用户命名一个连接的应用程序和其中的具体行动时使用此技能——读取一个邮箱,查询一个CMM,归档一个问题,更新一个电子表格,通过一个连接的搜索或刮取提供者运行一个查询. 每一次通话都到用户连接的应用…