Back to Details

user-manual-api-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

User Manual API Docs

用户手册API文档

  1. Inventory the real external, administrative, and internal API surfaces. Never infer that an endpoint is public from its route alone.
  2. Prefer checked-in contracts. For OpenAPI or AsyncAPI, lint and bundle before rendering. Read openapi.md.
  3. Produce separate audience bundles so internal or administrator operations cannot leak into public output.
  4. Document purpose, caller, authentication concept, permissions, method/path or channel, parameters, request/response schemas, statuses/errors, evidenced limits, versioning, and safe synthetic examples.
  5. Explain each operation in plain language before presenting technical reference.
  6. If no reliable contract exists, mark the generated reference as a draft and record the missing contract as documentation debt.
For a retailer integration API, publish order-submission examples to technical partners, keep refund administration endpoints in the authenticated edition, and exclude internal health or debug routes entirely.
  1. 盘点真实的外部、管理端及内部API接口。切勿仅通过路由推断某个端点为公开端点。
  2. 优先使用已签入的契约。对于OpenAPI或AsyncAPI，在渲染前先进行代码检查（lint）和打包。阅读openapi.md。
  3. 生成面向不同受众的独立文档包，避免内部或管理端操作泄露到公开输出内容中。
  4. 记录API的用途、调用方、认证概念、权限、方法/路径或通道、参数、请求/响应模式、状态/错误信息、已验证的限制、版本控制以及安全的合成示例。
  5. 在展示技术参考内容前，先用通俗易懂的语言解释每个操作。
  6. 如果不存在可靠的契约，将生成的参考文档标记为草稿，并将缺失契约的情况记录为文档债务。
以零售商集成API为例：向技术合作伙伴发布订单提交示例，将退款管理端点保留在需认证的文档版本中，并完全排除内部健康检查或调试路由。