指南
根据 OpenAPI 制作 API 文档:示例、Postman 与响应检查
将审核后的 OpenAPI 3.0 JSON 约定制作成可搜索参考与请求示例。检查已保存响应,保留未记录行为,并区分文档生成与真实 API 测试。
快速开始
让 AI 助手帮你完成
将这段提示粘贴到你正在使用的 AI 助手中:
使用 API Docs Studio 记录我审核后的 OpenAPI 3.0 JSON 约定。检查受支持范围,保留实际鉴权与错误,生成请求示例及 Postman 文件,再检查已清理的保存响应。明确保留未记录行为,不将执行请求作为文档生成的一部分。
助手能将 OpenAPI 制作成可用 API 文档吗?
API Docs Studio v1.0.1 根据受支持的 OpenAPI 3.0 JSON 约定生成可搜索 HTML 参考、Markdown、cURL/Python/Fetch 示例与 Postman v2.1 集合。包内工具使用 Python 3.10 及以上,可离线运行,无需依赖或 API 密钥。工作室只生成文件,不会调用文档中的服务。
生成示例前确认接口约定
- 阅读实际路由、测试或已确认约定。记录 API 版本、固定 HTTPS 服务地址、参数位置、必填输入、鉴权与已记录错误。明确标记拟议行为。
- 阅读 references/input.md。此版本接受 OpenAPI 3.0.0–3.0.3 JSON,不直接接受任意 YAML 或 OpenAPI 3.1。支持本地引用及有限结构校验;远程引用、递归与不支持的组合会被拒绝。
- 使用已清理示例请求体与令牌占位符。来源哈希标识所用字节,不能证明它们描述当前已部署实现。
生成虚构参考并检查已保存响应
安装完整内容包,阅读 SKILL.md,在包内目录运行,并使用新输出目录。第一条命令生成包内虚构 Northstar API 参考;第二条对指定操作和状态校验已保存示例响应。两条命令均不发送请求。
python3 scripts/build-docs.py --spec examples/openapi.json --output ./practice-api --demo
python3 scripts/check-response.py --spec examples/openapi.json --operation getWorkspace --status 200 --response examples/workspace-response.json使用前检查每条导出请求
- 打开 practice-api/index.html,搜索端点、选择操作并切换请求语言。将参数位置、URL 编码、鉴权占位符与响应状态同原约定对照。
- 下载实际代码示例、原始 OpenAPI、Markdown 与 Postman 集合。检查 quality.json 和交付清单。缺失错误说明应保留为待补项,不编造响应。
- 使用获准的真实约定时省略 --demo,重新生成并比较已清理的保存响应。有限结构检查通过,不能证明鉴权、副作用、业务规则、延迟或幂等性。不支持的断言需要独立测试。
检查当前示例产出 → — 将可见结果与本节说明的导出文件和检查对应起来。
将文档交给实现负责人
将审核后的约定、生成文件、警告与未解决问题一并保存。导入集合不能证明集成成功。真实测试属于独立授权任务;对服务执行示例前应审核凭据及创建、修改、删除操作。