一键在 Manus 中运行任何 Skill

check-apidoc

校验 OpenAPI 3.0 接口文档的结构合法性与接口完整性。分两层执行：脚本层（结构校验）+ AI 层（接口完整性）。触发场景：用户说 /check-apidoc、检查API文档、验证接口文档、文档校验；或由 campaign-apidoc skill 在生成完成后自动调用。参数支持文件路径或 module+layer 格式，例如 /check-apidoc /path/to/member_front.json 或 /check-apidoc meetup front。

在 Manus 中运行

概览

安装命令

npx skills add https://github.com/Mrs-Cui/personal-skills --skill check-apidoc

复制此命令并粘贴到 Claude Code 中以安装该技能

来源

Mrs-Cui/personal-skills

星标0

分支0

更新时间2026年4月25日 00:53

文件资源管理器

2 个文件

SKILL.md

readonly

name

check-apidoc

description

check-apidoc

对已生成的 OpenAPI JSON 文档执行两层校验，输出结构化报告。

工作流

第 1 步：解析参数，定位文件

支持两种参数格式：

格式 A：直接传文件路径

/check-apidoc /path/to/member_front.json

直接使用该路径作为目标文件。

格式 B：module + layer（campaign 项目快捷方式）

/check-apidoc meetup front
/check-apidoc rewardcenter infra

自动推导路径：{cwd}/../campaign-api-doc/reference/{module}_{layer}.json

（cwd 为当前工作目录，即 campaign 仓库根目录）

若文件不存在，立即报错退出。

第 2 步：脚本层校验（结构性）

运行内置校验脚本：

python3 ~/.claude/skills/check-apidoc/scripts/validate.py <文件路径>

脚本检查项：

JSON 格式合法性
顶级字段完整性（openapi、info、paths、components、tags）
所有 $ref 引用的 schema 是否在 components/schemas 中已定义
每个接口是否含 operationId、summary、tags、responses
responses 中禁止直接写 allOf（必须用 $ref 引用 schema）
deprecated 拼写检查
CommonResponse 若存在，检查是否有 properties 字段
时间戳字段是否有 "format": "int64"（警告级别）
x-stoplight.id 是否存在（警告级别，Stoplight 平台专用）
x-last-updated、x-source-handler 是否存在（警告级别，可选元数据）

若脚本报告 ❌ 错误，直接在报告中列出并终止，不进入第 3 步。 若只有 ⚠️ 警告，继续执行第 3 步。

第 3 步：AI 层校验（接口完整性）

从 JSON 的 info.x-source-handler 获取 handler 文件路径。若该字段不存在，跳过此步并在报告中注明。

第一步：统计 JSON 中的接口数

json_count = len(doc["paths"])

第二步：统计源码中的路由数

grep handler 文件中的路由注册行：

grep -n "\.Handle\|\.GET\|\.POST\|\.PUT\|\.DELETE\|\.PATCH" \
  <handler_path> | grep -v "^\s*//"

若结果为空，说明该文件本身不含路由注册，可能注册在主路由文件中（如 campaign 的 cmd/campaign/1_front.go）。此时提示用户手动确认，不强制报错。

统计有效路由行数（排除注释行）= source_count

第三步：对比

情况	结论
`json_count == source_count`	✅ 接口数匹配
`json_count < source_count`	❌ 文档缺少接口，列出源码中有但 JSON paths 中没有的路径
`json_count > source_count`	⚠️ 文档接口数多于源码，可能有多余条目

路径对比方法： 从 Grep 结果提取路由字符串（引号内的路径），与 JSON paths 的 key 做差集，列出缺失项。

第 4 步：输出报告

格式如下：

╔══════════════════════════════════════════════════╗
║  check-apidoc 校验报告：{filename}               ║
╚══════════════════════════════════════════════════╝

【脚本层】结构校验
  ✅ 无结构性错误
  ⚠️  1 条警告：info 缺少 x-source-handler

【AI 层】接口完整性
  ✅ 接口数匹配：JSON 75 个 / 源码 75 个
  — 或 —
  ❌ 缺少 3 个接口：
     · POST /api/v1/xxx/activate
     · GET  /api/v1/yyy/list
     · ...

【总结】
  ✅ 校验通过  — 或 —  ❌ 发现 N 个问题，需要修复

若发现 ❌ 错误，给出具体修复建议（是哪步骤出错、如何补充）。

注意事项

脚本层是客观检查，有 ❌ 就必须修复后重新生成
AI 层路由计数允许 ±1 的误差（handler 文件偶有非标准注册方式）
若 x-source-handler 不存在，跳过 AI 层并在报告中注明
x-last-updated、x-source-handler、x-stoplight.id 均为可选元数据，缺失只产生警告不报错

同仓库更多 Skills

同仓库

web-access

Mrs-Cui/personal-skills

所有联网操作必须通过此 skill 处理，包括：搜索、网页抓取、登录后操作、网络交互等。触发场景：用户要求搜索信息、查看网页内容、访问需要登录的网站、操作网页界面、抓取社交媒体内容（小红书、微博、推特等）、读取动态渲染页面、以及任何需要真实浏览器环境的网络任务。

2026-04-250

report-unittest-issues

Mrs-Cui/personal-skills

分析当前对话中 AI 单元测试过程遇到的问题，汇总为单个 issue 提交到 GitLab。手动触发，用于在单元测试完成后回顾问题并归档。触发方式：用户明确要求"报告单测问题"、"提交单测 issue"、"report unittest issues"或类似表述时使用。

2026-04-250

ai-code-review

Mrs-Cui/personal-skills

基于 git diff 和 CLAUDE.md 业务上下文，对代码变更进行结构化 Code Review，输出分级问题清单。 Use when: - 用户请求 Code Review，如"帮我 review"、"review 一下代码"、"/review 命令" - 开发者提交前自查代码质量 - 用户想验证代码是否符合业务规则约束 - pre-push hook 或 CI 流水线中自动触发 - 用户说"看看我这次改了哪些问题"、"有没有漏掉什么"

2026-04-250

campaign-apidoc

Mrs-Cui/personal-skills

为 campaign 项目的 Gin Handler 自动生成 OpenAPI 3.0 接口文档，输出到 campaign-api-doc 仓库。触发场景：用户说 /campaign-apidoc、生成接口文档、更新API文档、为某模块生成文档，或提到 campaign-api-doc。参数格式：/campaign-apidoc {module} {layer}，例如 /campaign-apidoc meetup front、/campaign-apidoc meetup admin、/campaign-apidoc member front。也支持 URL 前缀模式：/campaign-apidoc /api/v1/contra-invite。

2026-04-250

campaign-kb

Mrs-Cui/personal-skills

Campaign 项目技术知识库查询。当用户询问任何关于 campaign 系统的技术问题——包括服务、方法、模块、表结构、数据模型、业务流程、依赖关系、Kafka topic、定时任务等——都应触发此 skill。无需精确关键词匹配，只要问题涉及 campaign 代码库的技术细节即可。快捷命令：/kb

2026-04-250

claude-context

Mrs-Cui/personal-skills

为任意代码模块生成或更新 CLAUDE.md 上下文文件，让 AI 在开发时自动获取业务知识，无需每次重复解释背景。 Use when: - 用户请求为模块生成 CLAUDE.md，如"帮我生成上下文"、"建立这个模块的文档" - 用户请求更新已有 CLAUDE.md，如"更新文档"、"同步文档"、"我改了表结构" - 用户开始开发一个没有 CLAUDE.md 的模块 - 代码变更涉及数据库表结构、HTTP 接口、业务规则或外部依赖 - 用户运行 /gen-claude 或 /update-claude 命令

2026-04-250

来源

Mrs-Cui

Mrs-Cui/personal-skills

打开 GitHub 仓库查看创作者相关仓库

安装命令

下载

在 Manus 中运行

适用职业SOC

软件开发工程师计算机与数学类职业15-1252L4

name

check-apidoc

description

check-apidoc

对已生成的 OpenAPI JSON 文档执行两层校验，输出结构化报告。

工作流

第 1 步：解析参数，定位文件

支持两种参数格式：

格式 A：直接传文件路径

/check-apidoc /path/to/member_front.json

直接使用该路径作为目标文件。

格式 B：module + layer（campaign 项目快捷方式）

/check-apidoc meetup front
/check-apidoc rewardcenter infra

自动推导路径：{cwd}/../campaign-api-doc/reference/{module}_{layer}.json

（cwd 为当前工作目录，即 campaign 仓库根目录）

若文件不存在，立即报错退出。

第 2 步：脚本层校验（结构性）

运行内置校验脚本：

python3 ~/.claude/skills/check-apidoc/scripts/validate.py <文件路径>

脚本检查项：

JSON 格式合法性
顶级字段完整性（openapi、info、paths、components、tags）
所有 $ref 引用的 schema 是否在 components/schemas 中已定义
每个接口是否含 operationId、summary、tags、responses
responses 中禁止直接写 allOf（必须用 $ref 引用 schema）
deprecated 拼写检查
CommonResponse 若存在，检查是否有 properties 字段
时间戳字段是否有 "format": "int64"（警告级别）
x-stoplight.id 是否存在（警告级别，Stoplight 平台专用）
x-last-updated、x-source-handler 是否存在（警告级别，可选元数据）

若脚本报告 ❌ 错误，直接在报告中列出并终止，不进入第 3 步。 若只有 ⚠️ 警告，继续执行第 3 步。

第 3 步：AI 层校验（接口完整性）

从 JSON 的 info.x-source-handler 获取 handler 文件路径。若该字段不存在，跳过此步并在报告中注明。

第一步：统计 JSON 中的接口数

json_count = len(doc["paths"])

第二步：统计源码中的路由数

grep handler 文件中的路由注册行：

grep -n "\.Handle\|\.GET\|\.POST\|\.PUT\|\.DELETE\|\.PATCH" \
  <handler_path> | grep -v "^\s*//"

若结果为空，说明该文件本身不含路由注册，可能注册在主路由文件中（如 campaign 的 cmd/campaign/1_front.go）。此时提示用户手动确认，不强制报错。

统计有效路由行数（排除注释行）= source_count

第三步：对比

情况	结论
`json_count == source_count`	✅ 接口数匹配
`json_count < source_count`	❌ 文档缺少接口，列出源码中有但 JSON paths 中没有的路径
`json_count > source_count`	⚠️ 文档接口数多于源码，可能有多余条目

路径对比方法： 从 Grep 结果提取路由字符串（引号内的路径），与 JSON paths 的 key 做差集，列出缺失项。

第 4 步：输出报告

格式如下：

╔══════════════════════════════════════════════════╗
║  check-apidoc 校验报告：{filename}               ║
╚══════════════════════════════════════════════════╝

【脚本层】结构校验
  ✅ 无结构性错误
  ⚠️  1 条警告：info 缺少 x-source-handler

【AI 层】接口完整性
  ✅ 接口数匹配：JSON 75 个 / 源码 75 个
  — 或 —
  ❌ 缺少 3 个接口：
     · POST /api/v1/xxx/activate
     · GET  /api/v1/yyy/list
     · ...

【总结】
  ✅ 校验通过  — 或 —  ❌ 发现 N 个问题，需要修复

若发现 ❌ 错误，给出具体修复建议（是哪步骤出错、如何补充）。

注意事项

脚本层是客观检查，有 ❌ 就必须修复后重新生成
AI 层路由计数允许 ±1 的误差（handler 文件偶有非标准注册方式）
若 x-source-handler 不存在，跳过 AI 层并在报告中注明
x-last-updated、x-source-handler、x-stoplight.id 均为可选元数据，缺失只产生警告不报错