Agent Skills
返回列表
💻

OpenAPI 规范变更日志生成器

开发编程 更新于 2026.08.29

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

请根据 https://skillhub.cn/install/skillhub.md，安装 @user_3c6cb52e/openapi-spec-changelog-generator。

技能介绍

问题：API 规范演进时，变更信息散落在 diff 里

当团队维护 OpenAPI 3.x 规范文件时，接口的 breaking change、废弃标记（deprecated）或字段调整往往分散在两次提交的 diff 中。开发、测试和下游客户端维护者很难快速判断：这次规范更新会破坏谁？哪些端点已被标记废弃？schema 中哪些字段被移除或改名了？靠肉眼比对 openapi.yaml 的 diff 既慢又容易漏掉隐式破坏性变更，比如新增必填字段、请求体类型收窄等。

核心能力：基于 oasdiff 的语义级对比

这个技能围绕 oasdiff 库工作，将两份 OpenAPI 3.x 规范文件（通常是变更前后的两个版本）交给 oasdiff 做语义级对比，而不是逐行文本 diff。关键步骤大致是：

  • 输入两份规范：提供变更前后的 OpenAPI 3.x 文件，技能负责驱动对比流程
  • 执行语义比对：调用 oasdiff break 等核心检测，定位端点路径、HTTP 方法、参数、请求体与响应 schema 的破坏性变更
  • 识别废弃与模式修改：找出被标记 deprecated: true 的端点，以及 schema 层面的字段新增/删除/改名、类型变更、必填项调整
  • 输出结构化日志：结果可导出为 Markdown 或 JSON，方便直接贴进 PR 描述、Release Notes 或 CI 报告

适用边界与注意点

  • 仅覆盖 OpenAPI 3.x：不适用于 Swagger 2.0 或其他规范版本
  • 检测依赖 oasdiff 规则集：某些破坏性变更（如响应码语义变化）可能不会被判定，结果需结合团队自身约定复核
  • 技能本身不含已验证的安装说明：SKILL.md 中未提供可靠的安装与使用步骤，在接入敏感工作流（如自动发版）前，建议先在本地完整跑通并审阅上游项目
  • 输出是机器可读的事实清单，不是人工文案：面向工程流程很有用，但最终面向用户的变更公告仍需人工润色

使用场景

  • 升级依赖的 OpenAPI 规范后，对比新旧 `openapi.yaml` 生成破坏性变更清单。
  • 接口被标记 deprecated 后，汇总废弃端点写入发布说明。
  • 重构请求体 schema 时，用 oasdiff 检测字段删除与必填变更并输出 JSON。
  • CI 流水线拉取 PR 前后的 spec，生成 Markdown 变更日志贴进 PR 描述。

适合人员

  • 后端工程师：发布新版本前需要确认规范改动不会破坏现有客户端调用。
  • API 网关维护者：需明确哪些路由被废弃，通知下游租户安排迁移。
  • 技术文档工程师：要把 schema 改动整理成可读的变更日志放进发布文档。
  • CI/CD 流水线开发者：想在合并请求阶段自动获取结构化规范差异报告。