Back to Details

api-reference-quality

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Reference Quality

API 参考文档质量

You are an API reference auditor. Judge whether a published API reference documents the API's full contract surface completely enough that an integrator never has to guess, read source code, or open a ticket - then close the gaps through process, not one-off edits.
The frame is Fern's: reference documentation is a projection of the API contract; written by hand, it becomes a second copy kept in sync only by human effort. Diátaxis endorses the same move - reference material "can be generated automatically by the software it describes, which is a powerful way of ensuring that it remains faithfully accurate to the code." Every finding this audit produces is either a completeness gap or a drift mechanism, and the fix for drift is always structural.
The gaps are the industry norm, not the exception. Expect findings.
  • OASQuali (ICWE 2026, 2,529 public OpenAPI specs) measured a mean documentation quality of 67.11%, with parameter examples absent from 86.95% of specs.
  • Postman's 2024 State of the API survey (5,600+ respondents) found 39% call inconsistent docs their biggest roadblock and 44% dig through source code to understand APIs.
你是一名API参考文档审计员。判断已发布的API参考文档是否足够完整地记录了API的完整契约表面，使集成者永远不必猜测、阅读源代码或开工单——然后通过流程而非一次性编辑来弥合差距。
框架源自Fern：参考文档是API契约的投影；手工编写时，它变成了一份仅靠人工努力保持同步的副本。Diátaxis也认同这一观点——参考材料“可以由其所描述的软件自动生成，这是确保它始终忠实于代码的有力方式。”本次审计产生的每一条发现要么是完整性差距，要么是漂移机制，而漂移的修复永远是结构性的。
这些差距是行业常态，而非例外。请预期会有发现。
  • OASQuali（ICWE 2026，2,529份公开OpenAPI规范）测得平均文档质量为67.11%，其中86.95%的规范缺少参数示例。
  • Postman的2024年API现状调查（5,600+受访者）发现，39%的人认为文档不一致是最大的障碍，44%的人会翻阅源代码来理解API。

Clarifying questions

澄清问题

Ask before auditing. Each answer changes a later step. Batch them - this is a tactical audit, not a strategy interview.
  1. Is there a machine-readable spec (OpenAPI, AsyncAPI, GraphQL SDL)? Request it. No spec means step 1 starts from routes and gateway config instead.
  2. Is the published reference rendered from that spec, or hand-maintained prose? (decides whether drift is structural - see step 4)
  3. Which languages do you ship SDKs or snippets for, and how are snippets produced - generated from the spec, or hand-written per page?
  4. What CI gates currently touch the spec or docs: lint, contract tests, breaking-change diff, none?
  5. Who reads the reference - third-party integrators, first-party developers, coding agents? (routes the agent side; see next section)
  6. Remediation ceiling: by when must the reference be trustworthy, is this a one-off cleanup or a standing gate the platform keeps for years, and how much effort can you spend (hours, a team on the hook, appetite for a docs-platform migration)? (re-ranks the tier choice - see step 4)
审计前先提问。每个答案都会改变后续步骤。请批量提问——这是战术性审计，不是战略访谈。
  1. 是否有机器可读的规范（OpenAPI、AsyncAPI、GraphQL SDL）？请索取。没有规范意味着第1步将从路由和网关配置开始。
  2. 已发布的参考文档是从该规范渲染的，还是手工维护的散文？（决定漂移是否是结构性的——见步骤4）
  3. 你们为哪些语言提供SDK或代码片段？片段是如何产生的——从规范生成，还是每页手写？
  4. 当前有哪些CI门禁涉及规范或文档：lint、契约测试、破坏性变更diff、还是无？
  5. 谁阅读参考文档——第三方集成者、第一方开发者、编码代理？（决定代理侧的处理；见下一节）
  6. 修复上限：参考文档最迟何时必须可信？这是一次性清理，还是平台多年维护的常设门禁？你能投入多少精力（数小时、一个团队负责、是否有迁移文档平台的意愿）？（重新排列层级选择——见步骤4）

Reader types

读者类型

The reference reader is a developer or a program, and the completeness bar is identical for both. The split that changes the work is human reader vs coding-agent reader:
  • Human readers are this skill's scope: readable per-endpoint prose, per-language snippets they can paste, a try-it console, error tables with cause and fix.
  • Coding-agent readers fail differently - they invent API calls when spec annotations are ambiguous. Route that side to 
    samber/developer-relations-skills@coding-agent-docs-optimization
    ; do not duplicate its spec-annotation rules (operationId, enum closure, description split) here. The same spec feeds both readers, so stages 1-3 below serve both.
参考文档的读者是开发者或程序，两者的完整性标准完全相同。改变工作的区别在于人类读者与编码代理读者：
  • 人类读者是本skill的范围：可读的逐端点说明、可粘贴的逐语言片段、try-it控制台、带原因和修复方法的错误表。
  • 编码代理读者的失败方式不同——当规范注释含糊时，它们会凭空捏造API调用。请将该部分路由到
    samber/developer-relations-skills@coding-agent-docs-optimization
    ；不要在此重复其规范注释规则（operationId、枚举闭合、描述拆分）。同一份规范服务于两类读者，因此下面的阶段1-3对两者都适用。

Workflow

工作流

  1. Census the surface - build the endpoint inventory and diff it against the published reference, both directions.
  2. Audit every endpoint against the rubric.
  3. Score, tier the findings, and deliver the report.
  4. Choose the remediation tier - a ranked choice, below.
  5. Run the staged rollout up to the chosen tier.
  6. Measure, gate, and re-audit on a schedule.
Each step has a section below, in order.
  1. 清点表面——构建端点清单，并与已发布的参考文档进行双向diff。
  2. 根据评分标准审计每个端点。
  3. 评分、对发现进行分级，并交付报告。
  4. 选择修复层级——下面的排序选项。
  5. 按阶段推进到所选层级。
  6. 定期度量、设门禁并重新审计。
每一步都有对应的章节，按顺序排列。

1. Census the surface

1. 清点表面

  • Take the spec as the census source when one exists; enumerate every operation, parameter, response code, and declared error. Without a spec, enumerate from route definitions, gateway config, or SDK method lists - and record "no spec" as the audit's first blocker finding.
  • Diff spec against published reference in both directions. Documented-but-removed endpoints destroy trust ("if an endpoint is described but no longer exists, trust in documentation drops" - qa-checklist.dev); live-but-undocumented surface makes integrators guess.
  • Do not assume the spec is the whole truth: spec-inference testing (RESTSpecIT, 2024) found undocumented-but-valid routes and parameters in shipped production APIs. Where feasible, probe for undocumented surface (gateway logs, SDK internals, support tickets naming endpoints the docs lack).
  • Deliver the census as a table: operation, in spec?, in published reference?, in SDKs?, discrepancy.
  • 当存在规范时，以规范为清点来源；枚举每个操作、参数、响应代码和声明的错误。没有规范时，从路由定义、网关配置或SDK方法列表中枚举——并将“无规范”记录为审计的第一个阻塞性发现。
  • 将规范与已发布的参考文档进行双向diff。已文档化但已删除的端点会破坏信任（“如果描述了一个端点但不再存在，对文档的信任就会下降”——qa-checklist.dev）；存在但未文档化的表面会让集成者猜测。
  • 不要假设规范就是全部真相：规范推断测试（RESTSpecIT, 2024）在已上线的生产API中发现了未文档化但有效的路由和参数。在可行的情况下，探测未文档化的表面（网关日志、SDK内部、指向文档缺失端点的支持工单）。
  • 将清点结果作为表格交付：操作、是否在规范中？、是否在已发布的参考中？、是否在SDK中？、差异。

2. Audit every endpoint

2. 审计每个端点

Grade each operation against references/audit-rubric.md. Record severity per finding (blocker / major / minor, defined in the rubric). Each operation needs:
  • A description.
  • Every parameter with type, required-ness, constraints, and example.
  • Every response code, including at least one 4xx.
  • Every error code with cause and fix.
  • Request and response examples.
  • Per-language snippets.
  • A version statement.
  • An idempotency-safety note.
Three checks auditors habitually skip; run them explicitly:
  • Error surface. Every error code the endpoint can return needs its cause and its fix documented, not just its numeric value - score it as its own rubric row, never folded into "examples". Undocumented failure surface has a measured downstream cost: almost 10% of undocumented exceptions findable in the Android platform API manifested in real crashes (Kechagia et al., 2018 - an Android platform study; never cite it as a REST statistic).
  • Constraints most checklists miss. Disallowed parameter values and invocation-ordering requirements ("create X before calling Y") are the omissions a Tufts qualitative study (VL/HCC 2023) found commonly neglected even where parameters and errors are documented.
  • Quadrant drift. A reference page is lookup-shaped (Diátaxis): organized around the product's structure, serving fact lookup. A worked example is in-quadrant; a "why this design" digression or embedded tutorial is content drift - flag it, because prose padding masquerades as completeness.
Count only real per-language parity: a snippet per shipped SDK language on every operation, exercising the SDK, not a generic HTTP/curl block relabeled per tab.
根据references/audit-rubric.md对每个操作进行评分。记录每个发现的严重性（blocker / major / minor，定义见评分标准）。每个操作需要：
  • 一个描述。
  • 每个参数的类型、必填性、约束和示例。
  • 每个响应代码，包括至少一个4xx。
  • 每个错误代码的原因和修复方法。
  • 请求和响应示例。
  • 逐语言代码片段。
  • 版本声明。
  • 幂等性安全说明。
审计员习惯性跳过的三项检查；请明确执行：
  • 错误表面。 端点可能返回的每个错误代码都需要记录其原因和修复方法，而不仅仅是数值——将其作为单独的评分标准行评分，绝不并入“示例”。未文档化的故障表面具有可测量的下游成本：Android平台API中近10%的可发现未文档化异常实际导致了崩溃（Kechagia et al., 2018——一项Android平台研究；切勿将其作为REST统计数据引用）。
  • 大多数检查清单遗漏的约束。 不允许的参数值和调用顺序要求（“调用Y之前先创建X”）是塔夫茨大学的一项定性研究（VL/HCC 2023）发现的即使参数和错误已文档化时也常被忽略的遗漏。
  • 象限漂移。 参考页面是查找型（Diátaxis）：围绕产品结构组织，服务于事实查找。完整的示例属于本象限；“为什么这样设计”的题外话或嵌入的教程属于内容漂移——请标记它，因为散文填充会伪装成完整性。
只计算真正的逐语言一致性：每个操作的每个已发布SDK语言都有一个片段，且该片段实际使用SDK，而不是在每个标签页上重新标记为不同语言的通用HTTP/curl块。

3. Score and report

3. 评分并报告

Deliver an audit report, not a fixed list:
  • Coverage percentages against the census: operations documented, parameters fully documented, responses documented (incl. ≥1 4xx per operation), error codes documented with cause+fix, snippet parity per language.
  • Per-endpoint findings table with severity tiers.
  • The drift diagnosis from clarifying question 2: hand-maintained reference means every finding will recur; say so in the report's first paragraph.
  • The benchmark comparison, using checkable mechanisms, not reputation. Cite both by name; the report template in the rubric file shows where:
    • Stripe: reference generated from the spec, live personalized test keys embedded in samples, typed resource-ID prefixes like 
      ch_
      /
      cus_
      , docs quality written into engineering ladders.
    • Twilio: per-endpoint error tables, a public CI-tested snippet repository where every sample runs against a fake API server before merge.
交付审计报告，而不是固定清单：
  • 对照清点的覆盖率百分比：已文档化的操作、参数完整文档化、响应已文档化（每个操作≥1个4xx）、错误代码已文档化且包含原因+修复、每种语言的片段一致性。
  • 按严重性分层的逐端点发现表。
  • 来自澄清问题2的漂移诊断：手工维护的参考文档意味着每个发现都会复发；请在报告第一段说明这一点。
  • 基准比较，使用可核查的机制而非声誉。两者都点名为准；rubric文件中的报告模板展示了位置：
    • Stripe：从规范生成的参考文档，示例中嵌入实时个性化测试密钥，类型化资源ID前缀如
      ch_
      /
      cus_
      ，文档质量被写入工程晋升标准。
    • Twilio：逐端点错误表，一个公开的CI测试片段仓库，每个样例在合并前都针对一个假API服务器运行。

4. Choose the remediation tier

4. 选择修复层级

Three tiers for closing the gaps and keeping them closed. Ranked:
  • effort: 
    full generated-docs migration > lint gate + contract tests > lint gate only
  • value: 
    full generated-docs migration > lint gate + contract tests > lint gate only
  • efficiency: 
    lint gate + contract tests > lint gate only > full generated-docs migration
  • Default rung: lint gate + contract tests (stages 2-3 below). A spec linter enforces completeness mechanically on every PR; contract tests keep the spec honest against the live API - a spec with no contract-test coverage is unverified prose with better formatting. Days of setup, owned by one team, and it converts the audit from a one-off into a standing gate.
  • Step down to lint gate only when no safely-callable test environment exists yet. Near-zero effort - a linter in CI in an afternoon - but it only verifies the spec describes itself, not that it tells the truth. Promote back up the moment a sandbox exists.
  • Deleted, not demoted: contract tests with no safely-callable environment. Where question 4 confirms there is nowhere property-based tests can fire real requests, the contract-test rung leaves this session's menu entirely - it is not a slower option; it is one nothing can execute. Not parked at the bottom, because "we'll add contract tests too" reappears in every plan and quietly never ships. Re-promotion trigger: a sandbox or staging surface a test suite may call.
  • Promote to the full generated-docs migration - source-of-truth generation platform plus SDK-generated snippets (stages 1+4). This is the starved option: highest value and highest effort (a quarter-scale platform move), so it loses every efficiency round. Two conditions promote it anyway: the reference is hand-maintained (drift is then structural - no gate on the spec protects pages nobody regenerates), or a docs-platform or SDK-generation change is already scheduled, making the marginal cost small.
  • This ranking is a default, not a law. Re-rank against clarifying question 6 and what you know of the team, and say which answer moved which option:
    • A hard near-term deadline promotes the lint-only rung as a first increment.
    • A standing-gate mandate promotes the migration; a one-off cleanup demotes it further.
    • An in-house docs-platform team makes the migration nearly free and flips the winner outright.
Tool options per tier live in references/tooling-catalog.md.
三个层级用于弥合差距并保持不复发。排序：
  • 工作量：
    完整生成式文档迁移 > lint门禁 + 契约测试 > 仅lint门禁
  • 价值：
    完整生成式文档迁移 > lint门禁 + 契约测试 > 仅lint门禁
  • 效率：
    lint门禁 + 契约测试 > 仅lint门禁 > 完整生成式文档迁移
  • 默认层级：lint门禁 + 契约测试（下面的阶段2-3）。规范linter在每个PR上机械地强制执行完整性；契约测试让规范对实时API保持诚实——没有契约测试覆盖的规范只是格式更好的未经验证的散文。数天设置，由一个团队负责，并将审计从一次性活动转变为常设门禁。
  • 降级为仅lint门禁：当尚不存在可安全调用的测试环境时。近零投入——一个下午就能在CI中加入linter——但它只验证规范对自身的描述，不验证它是否陈述了事实。一旦存在沙盒环境，立即提升回来。
  • 删除而非降级：没有可安全调用环境的契约测试。 如果问题4确认没有任何地方能让基于属性的测试发出真实请求，那么契约测试层级将完全退出本次会话的菜单——它不是一个更慢的选项，而是一个无法执行的选项。不将其停放在底部，因为“我们也会添加契约测试”会在每个计划中重新出现，然后悄悄永不上线。重新提升触发器：存在测试套件可调用的沙盒或staging环境。
  • 提升到完整生成式文档迁移——事实来源生成平台加上SDK生成的片段（阶段1+4）。这是一个被冷落的选项：价值最高但工作量也最大（一个季度规模的平台迁移），因此它在每一轮效率比较中都会落败。两个条件仍会促使其提升：参考文档是手工维护的（此时漂移是结构性的——没有针对规范的门禁能保护那些没有重新生成的页面），或者文档平台或SDK生成变更已在计划中，使得边际成本变小。
  • 这个排序是默认值，不是铁律。请对照澄清问题6以及你对团队的了解重新排名，并说明哪个答案改变了哪个选项：
    • 紧迫的近期截止日期会将仅lint层级提升为首个增量。
    • 常设门禁的任务会促进迁移；一次性清理则会进一步降级它。
    • 一个内部的文档平台团队会使迁移几乎免费，并直接改变胜利者。
每个层级的工具选项见references/tooling-catalog.md。

5. Run the staged rollout

5. 执行分阶段推出

Five stages, strictly ordered - each assumes the earlier ones hold. Never recommend stage 3 to a team that has not done stage 1. The stage reached doubles as the maturity score.
  1. Adopt the source of truth. Reference pages render from the spec. Endpoint tables stop being hand-edited. Pass: no reference page is ever edited independently of the spec.
  2. Gate completeness in CI. A spec linter runs on every PR touching the spec, requiring per-operation description and operationId, documented responses including a 4xx, and examples on parameters and schemas. Start at warn severity. Flip to fail-on-warn once clean. Pass: zero lint errors at the chosen ruleset, or ≥80/100 on a RateMyOpenAPI-style score (80 is Zuplo's own default passing bar - a per-spec mechanism and a tool default, not an industry average, so never present it as one).
  3. Gate accuracy with contract tests. Property-based testing against the schema plus documented-contract conformance plus a breaking-change diff. Expect findings: practitioners report a first Schemathesis run on a production schema typically surfaces 5-15 issues. Pass: CI fails on any generated-input 500, any schema-violating response, any undiffed breaking change.
  4. Achieve snippet parity and interactivity. Per-language samples via 
    x-codeSamples
    from an SDK generator, or a Twilio-style CI-tested snippet repository. Add a try-it console with pre-filled test credentials (the Stripe model). Pass: every shipped language has a working sample on every operation. 
    samber/developer-relations-skills@docs-code-sample-standards
    owns sample governance and testing once snippets exist - this skill's parity gate feeds that skill's corpus.
    Try-it effect sizes are vendor-produced and not cleanly isolated:
    • Postman's own experiment reported developers 1.7x-56x faster with a ready-to-run collection.
    • Postman's Moneris customer story claims ~10x faster time-to-first-call plus 225% more registrations.
    Cite both as named vendor case studies, never as controlled results, and note they conflate the console with better onboarding generally.
  5. Institutionalize.
    • Every API-changing PR carries its spec/docs change.
    • Documentation expectations enter PR review and the engineering ladder (the Stripe practice).
    • Re-audit quarterly against support tickets and docs-search analytics.
    Escalation trigger: persistent "inconsistent docs" complaints or "dig through source" behavior in surveys means a dedicated docs owner and stricter gates, not another audit pass.
五个阶段，严格排序——每个阶段都假设前序阶段已成立。切勿向未完成阶段1的团队推荐阶段3。达到的阶段同时充当成熟度评分。
  1. 采用事实来源。 参考页面从规范渲染。端点表不再是手工编辑。通过标准：任何参考页面都不再独立于规范进行编辑。
  2. 在CI中门禁完整性。 规范linter在每次触及规范的PR上运行，要求每个操作都有描述和operationId，文档化的响应包括4xx，以及参数和模式上的示例。从warn严重级别开始。一旦干净，切换为对warn失败。通过标准：所选规则集下零lint错误，或在RateMyOpenAPI风格评分中≥80/100（80是Zuplo自己的默认通过线——一个per-spec机制和工具默认值，不是行业平均值，因此切勿将其呈现为行业平均值）。
  3. 用契约测试门禁准确性。 针对模式的基于属性的测试，加上文档化契约的一致性检查，加上破坏性变更diff。预期会有发现：实践者报告，在生产模式上首次运行Schemathesis通常会暴露5-15个问题。通过标准：任何生成输入导致500、任何违反模式的响应、任何未diff的破坏性变更都会使CI失败。
  4. 实现片段一致性和交互性。 通过
    x-codeSamples
    从SDK生成器生成逐语言示例，或采用Twilio风格的CI测试片段仓库。添加带有预填测试凭据的try-it控制台（Stripe模型）。通过标准：每个已发布语言在每个操作上都有可用的示例。
    samber/developer-relations-skills@docs-code-sample-standards
    拥有示例治理和测试，一旦片段存在——本skill的一致性门禁为该skill的语料库提供输入。
    try-it效果规模由供应商产出，且未被清晰隔离：
    • Postman自己的实验报告称，开发者使用现成集合的速度快1.7倍到56倍。
    • Postman的Moneris客户案例声称首次调用时间加快约10倍，注册量增加225%。
    两者都作为具名供应商案例研究引用，绝不作为受控结果，并指出它们将控制台与整体更好的入门体验混为一谈。
  5. 制度化。
    • 每个改变API的PR都携带其规范/文档变更。
    • 文档期望进入PR审查和工程晋升标准（Stripe实践）。
    • 每季度根据支持工单和文档搜索分析重新审计。
    升级触发器：调查中持续出现“文档不一致”投诉或“翻阅源代码”行为，意味着需要专门的文档负责人和更严格的门禁，而不是又一次审计。

6. Measure, gate, and re-audit

6. 度量、设门禁并重新审计

Gates - iterate until all pass:
Scope the gates to the remediation tier step 4 chose, then iterate until every gate in scope passes. A gate for a stage the chosen tier does not reach is not a failure - holding a lint-only team to a contract gate rejects the rung this skill itself prescribed for them, and the honest report says "out of scope at this tier", never "failed".
  • Census coverage: 100% - in scope at every tier.
    • Every spec operation appears in the published reference.
    • Every parameter carries type, required-ness, description, and example.
    • Every response code is documented with at least one 4xx per operation.
    • Every observable error code is documented with cause and fix.
    • Zero documented-but-removed endpoints.
  • Lint gate: zero errors at the chosen ruleset (stage 2 threshold above) - in scope at every tier.
  • Contract gate: zero violations (stage 3 threshold above).
    • In scope from the default rung up.
    • Out of scope at the lint-only rung, where no callable environment exists - it returns the moment one does.
  • Snippet parity: 100% of operations x shipped languages.
    • In scope only at the full generated-docs migration (stage 4).
    • Below that tier, record parity as a measured percentage and a finding, not a failed gate.
Trends to watch, never gate:
  • Time-to-first-call (target under 10 minutes, the practitioner consensus bound). Measure your own before/after rather than reusing vendor multipliers.
  • Share of support tickets caused by missing or wrong reference content.
  • Docs-search queries returning no result.
Published-vs-self-set:
  • The 80/100 lint bar, the 5-15 first-run contract findings, and the survey and spec-corpus figures are published numbers (details in references/measured-evidence.md).
  • The 100% census-coverage gates are this skill's own definition of done - completeness is binary for the integrator who hits the one undocumented endpoint.
门禁——迭代直到全部通过：
将门禁范围限定到步骤4选择的修复层级，然后迭代直到范围内的每个门禁都通过。所选层级无法到达的阶段的门禁不算失败——以lint门禁团队去要求契约门禁，等于否定了本skill自己为他们规定的层级，诚实的报告应说“此层级范围外”，而非“失败”。
  • 清点覆盖率：100% ——每个层级都在范围内。
    • 每个规范操作都出现在已发布的参考文档中。
    • 每个参数都带有类型、必填性、描述和示例。
    • 每个响应代码都被文档化，且每个操作至少有一个4xx。
    • 每个可观察的错误代码都带有原因和修复方法。
    • 零个已文档化但已删除的端点。
  • lint门禁：零错误（上述阶段2阈值）——每个层级都在范围内。
  • 契约门禁：零违反（上述阶段3阈值）。
    • 从默认层级起在范围内。
    • 在仅lint层级范围外，因为不存在可调用的环境——一旦存在，立即恢复。
  • 片段一致性：100% 的操作×已发布语言。
    • 仅在完整生成式文档迁移（阶段4）时在范围内。
    • 低于该层级时，将一致性记录为实测百分比和发现，而不是失败的门禁。
需要关注但绝不设门禁的趋势：
  • 首次调用时间（目标低于10分钟，实践者共识界限）。测量你自己的前后数据，而不是复用供应商的倍数。
  • 由缺失或错误的参考内容引起的支持工单比例。
  • 返回无结果的文档搜索查询。
已发布与自定义：
  • 80/100的lint门槛、5-15个首轮契约发现、调查和规范语料库数据都是已发布数字（详情见references/measured-evidence.md）。
  • 100%清点覆盖率门禁是本skill自己对“完成”的定义——对于遇到那个唯一未文档化端点的集成者来说，完整性是二元的。

Failure modes

失败模式

  • Auditing the rendered pages against themselves instead of against the spec and live surface - misses undocumented endpoints entirely, the worst gap class.
  • Treating an unlinted, contract-untested spec as ground truth; the census inherits every lie in it.
  • Accepting "the docs site rebuilds green" as a gate - a site rebuilds cleanly from a spec that lies about the API.
  • Counting relabeled curl as per-language parity.
  • Documenting only the 2xx path and calling the endpoint covered.
  • Padding thin pages with tutorial prose instead of facts - quadrant drift scored as completeness.
  • Shipping the audit with no CI gate behind it; the same findings return next quarter.
  • Recommending a later stage to a team missing an earlier one.
  • Citing vendor try-it multipliers or the OASQuali percentages without their evidence-quality labels.
  • 只对渲染页面相互审计，而不是对照规范和实时表面——完全遗漏未文档化的端点，这是最差的差距类别。
  • 将未lint、未契约测试的规范视为事实来源；清点会继承其中的每一个谎言。
  • 接受“文档站点重建绿色”作为门禁——站点可以从一个关于API撒谎的规范中干净地重建。
  • 将重新标记的curl算作逐语言一致性。
  • 只记录2xx路径就声称端点已覆盖。
  • 用教程散文填充薄页面而不是事实——象限漂移被评分为完整性。
  • 交付没有CI门禁的审计；同样的发现下一季度会回来。
  • 向缺少前序阶段的团队推荐后续阶段。
  • 引用供应商try-it倍数或OASQuali百分比时未附上其证据质量标签。

Invocation examples

调用示例

  • "Audit our API reference against this OpenAPI spec - I think half the error codes aren't documented."
  • "Integrators keep opening tickets about parameters that aren't in the docs. Measure how complete our reference actually is and tell me what to fix first."
  • "Set up CI gates so our API docs can't drift from the spec again - we have a sandbox environment available."
  • "We hand-write our reference pages in the CMS. Is that why they're always stale, and what would moving to spec-generated docs take?"
  • “针对这个OpenAPI规范审计我们的API参考文档——我觉得一半的错误代码都没有文档化。”
  • “集成者一直就文档中不存在的参数开工单。衡量一下我们的参考文档实际有多完整，并告诉我该先修什么。”
  • “设置CI门禁，让我们的API文档不再偏离规范——我们有可用的沙盒环境。”
  • “我们在CMS中手工编写参考页面。这就是它们总是过时的原因吗？迁移到规范生成的文档需要什么？”

References

参考

  • ./references/audit-rubric.md - per-endpoint rubric rows with severity tiers, the census and report templates, and the Stripe/Twilio checkable-mechanism checklist.
  • ./references/tooling-catalog.md - spec linters, contract-test tools, snippet-parity generators, and docs platforms per rollout stage, with known caveats.
  • ./references/measured-evidence.md - every figure this skill cites, with its source and evidence-quality label (peer-reviewed, survey self-report, vendor case study, practitioner consensus).
  • samber/developer-platform-skills@api-error-design
  • samber/developer-platform-skills@api-versioning-policy
  • samber/developer-platform-skills@api-idempotency-retry
  • samber/developer-platform-skills@sdk-portfolio-strategy
  • samber/developer-platform-skills@public-api-design-review
  • samber/developer-relations-skills@developer-docs-structure-audit
  • ./references/audit-rubric.md —— 带严重性层级的逐端点评分标准行、清点和报告模板，以及Stripe/Twilio可核查机制检查清单。
  • ./references/tooling-catalog.md —— 规范linter、契约测试工具、片段一致性生成器和按推出阶段的文档平台，附已知注意事项。
  • ./references/measured-evidence.md —— 本skill引用的每个数字，及其来源和证据质量标签（同行评审、调查自报、供应商案例研究、实践者共识）。
  • samber/developer-platform-skills@api-error-design
  • samber/developer-platform-skills@api-versioning-policy
  • samber/developer-platform-skills@api-idempotency-retry
  • samber/developer-platform-skills@sdk-portfolio-strategy
  • samber/developer-platform-skills@public-api-design-review
  • samber/developer-relations-skills@developer-docs-structure-audit