Agent Skills
返回列表
💻

API 文档专家

开发编程 更新于 2026.08.30

将以下提示词粘贴到你的 AI 对话框中:

请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/zhaono1-agent-playbook-api-documenter。

技能介绍

你在补什么缺口

接口已经能跑,但对外只剩 Postman 集合或零散注释时,合作方和前端很难对齐字段含义、错误码和鉴权方式。OpenAPI(Swagger)能把 HTTP 路径、参数、请求体、响应和模型收成一份可机器读取的契约,后续可挂到 Swagger UI、代码生成或网关校验上。难点往往不在「有没有 yaml」,而在 operationId、tags 分组、共享 Schema 引用,以及 4xx/5xx 是否按统一结构写全。

技能如何组织文档

在你要写 API 文档、建 OpenAPI/Swagger 规范或做 API reference 时,技能会按规范结构逐项展开:

  • 端点:summary、operationId、description、tags、responses 为必备;parameters、requestBody(POST/PUT/PATCH)、security、deprecated 按需补全。
  • Schema:共用类型用 references,属性带说明;字符串标明 format(如 email、uuid、date-time);复杂结构配 examples,并标注 required。
  • 鉴权与错误:单独说明认证要求;错误体采用统一格式,并覆盖常见状态码(如 400、401、404、422、500 等)。

技能还提供从代码生成 OpenAPI、校验 spec 的脚本思路,并可对照 references/openapi-template.yaml 与 references/examples/ 下的示例对齐写法。

适用边界

它聚焦 文档与规范撰写,不负责替你实现业务接口或选定网关产品。若项目尚未稳定路由与 DTO,应先冻结接口再落 spec,否则 deprecated 与版本说明会反复改。

使用场景

  • 微服务联调前要把 REST 路由、查询参数和统一错误体写成 OpenAPI 3.x
  • 从现有 Spring/FastAPI 路由整理 operationId、tags 和 responses 产出可发布参考页
  • POST 接口的请求体 Schema 需标明 required、format 与示例供前端生成类型
  • 合并多团队的公共模型时用 $ref 抽共享 Schema,避免重复定义

适合人员

  • 负责对外 SDK 与合作伙伴对接的后端,需要一份可校验的 OpenAPI 契约
  • 维护内部 API 门户的技术写作,要把零散注释整理成带 tags 与状态码表的参考文档
  • 在 CI 中对接 spectral 或 openapi-generator、需先补齐 security 与标准错误响应的 DevOps 工程师
  • 新服务上线前由 Tech Lead 牵头冻结接口形状并输出首版 Swagger 规范