DSH VERTICAL KIT · 接口文档检查 / API 文档检查
接口文档检查清单
它决定一件事:这份接口文档是否交代了怎么调、怎么证明身份、失败长什么样。
检查规则
| 规则 | 判定 |
|---|---|
endpoints-missing | 没有「METHOD + 路径」形式的端点 → error |
examples-missing | 没有代码块示例 → error |
auth-missing | 没有鉴权说明(鉴权/认证/Authorization/Bearer)→ error |
error-shape-missing | 没有错误响应说明(错误/失败/4xx/5xx)→ warn |
用法
npx api-doc-check api.md --jsonnpx api-doc-check api.md --min-endpoints 5
真实输入输出
输入
# 接口说明
我们的接口在 /v1/items 上,可以用。$ api-doc-check api-sample.md
error endpoints-missing 第0行 没有「METHOD + 路径」形式的端点(认得:GET /v1/items、POST /v1/orders),下限 1——只有路径没有动词的行不算,单独一行路径无法被调用
error examples-missing 第0行 代码块只有 0 个(下限 1)——接口文档至少要有一个请求或响应示例
error auth-missing 第0行 全文没有鉴权说明(认得:鉴权、认证、Authorization、API key、Bearer)——不知道怎么证明身份的接口文档不可用
warn error-shape-missing 第0行 没有错误响应的说明(认得:错误、失败、4xx、5xx)——只写成功的文档让读者猜失败长什么样
fail: 0 endpoints, 0 examples, 3 errors, 1 warnings
出口码:1。输出为真实 CLI 运行的逐字结果,由测试与工具保持同步。
出口码:0 干净、1 有发现、2 用法或读文件错误。--json 输出机器可读结果。DSH 内同样的函数在 POST /api-doc-check/api({"text":"…"} 或 {"path":"…"}),面板与 CI 调同一实现。
这是清单,不是专业人士。合同检查不是法律意见,发票检查不判税务合规,listing 检查不判商业价值。每条发现都是文本里可判定的结构缺陷,带行号。
只验书记层面,不验接口正确性:它验证文档写了方法+路径、有示例、点了鉴权、说了失败长什么样;接口是否真那样行为,靠契约测试。 · dsh-vertical-kit · 通用检查(哈希/引用/结构/表格/数字)在 dsh-verify-kit