API Reference 端点页面契约

大理论

API reference 端点页把机器可读规范、人类阅读路径和可执行示例放在同一界面里。健康的端点文档需要回答：这个 endpoint 做什么、method/path 是什么、需要哪些 auth scope、哪些参数必填、请求体如何构造、成功和失败会返回什么、错误如何恢复、能不能安全试运行、示例是否可以直接复制。

小知识点

1. 首屏必须明确 endpoint identity：method、path、summary、operationId/tag、版本、稳定性、弃用说明和 source spec。
2. 参数按 path、query、header、cookie 分组；required 优先；每项至少包含 type、description、default、enum/format、constraint 和 example。
3. 请求体要同时展示 schema 与 example，尤其是 nested required fields、content type、nullable、file upload、validation 和 idempotency。
4. 响应不能只写 200；要有状态码矩阵，覆盖 2xx、validation/auth/permission、not found/conflict、rate limit、async accepted 和 5xx，并写明 recovery 与 retry safety。
5. Try-it 控制台默认应使用 sandbox 或明确环境；POST/PATCH/DELETE 等写操作要确认，绝不能把真实 secret、客户 ID 或生产写入当作普通示例。
6. 代码示例要调用代码复制契约：cURL/SDK tabs、placeholder、copyText、复制反馈、语法高亮、失败 fallback 和移动端局部滚动。
7. 三栏 API docs 在桌面很好扫视，但移动端和 200% zoom 要折叠为稳定单列；schema/code 可以局部滚动，页面不能整页横向溢出。

设计判断

如果开发者能从同一页完成理解 endpoint、配置鉴权、填写参数、复制示例、运行 sandbox 请求、读懂成功/错误响应和找到下一步恢复动作，这个 API reference 契约成立。若页面只有漂亮的路径列表和 200 example，仍然只是半成品。

实现建议

建立 ApiEndpointContract：id、method、path、summary、auth、parameters、requestBody、responses、examples、tryIt、pagination、rateLimitNote、sourceSpecHref 和 renderer。使用生成器时仍要补手工 QA：真实示例与 schema 同步、status matrix 完整、destructive try-it 防护、auth placeholder、安全日志、keyboard tabs、mobile schema table、copy fallback 和 source spec 链接。渲染器选择按任务：Swagger UI 偏标准交互式 OpenAPI 探索，Redoc 偏三栏静态 reference，Scalar 偏现代自托管 reference/API client。

反例/风险

只展示 200 response；把 auth scope 放到页尾；所有参数混在一个表；try-it 默认打生产写接口；cURL 示例复制出行号和 shell prompt；error schema 与真实 API 不一致；移动端右侧示例栏覆盖正文；OpenAPI source 更新后手写示例过期。

案例分析

OpenAPI Specification 把 API surface 定义成可由人和机器理解的语言无关接口，并把 paths、components、webhooks 等作为描述结构。Swagger UI 的价值在于可视化并交互 OpenAPI 资源，适合标准 try-it 探索；Redoc 的默认三栏布局把左侧搜索/导航、中央文档和右侧 request/response examples 分开，说明 endpoint reference 需要同时支持定位、阅读和示例比较；Scalar 把 API reference 和 API client 放进同一开源平台，说明现代 docs 越来越靠近可执行调试界面。可学习点是：schema、layout 和 try-it 都不是单独答案，端点页需要一份安全、可读、可执行的合同。

来源链接

OpenAPI Specification: https://swagger.io/specification/ OpenAPI Initiative GitHub: https://github.com/oai/openapi-specification Swagger UI: https://swagger.io/tools/swagger-ui/ Swagger UI GitHub: https://github.com/swagger-api/swagger-ui Redoc docs: https://redocly.com/docs/redoc Redoc GitHub: https://github.com/Redocly/redoc Scalar: https://scalar.com/ Scalar GitHub: https://github.com/scalar/scalar WAI-ARIA APG Tabs: https://www.w3.org/WAI/ARIA/apg/patterns/tabs/ WCAG Reflow: https://www.w3.org/WAI/WCAG21/Understanding/reflow.html