如何用 OpenAPI 记录真实 API 契约。
API 规范应反映真实契约，包括错误和认证。标明未知行为，不要编造看似完善的端点描述。
按任务需求调整流程。
使用指定 OpenAPI 版本，记录实际端点、参数、认证和响应契约。包括已知错误并标明未知行为，不要依靠假设拼出看似完整的契约。
- 你需要提供什么
- 已核实的端点描述和示例响应。
- 你会得到什么
- 标出未确定契约的 OpenAPI 草案。
查看输入和结果。
演示用输入和输出 · 教学示例，并非 WebAct 实时运行结果
示例 个输入项
Produce an OpenAPI 3.1.1 JSON fragment for fictional GET /items. Confirmed response: status 200, application/json array, each item requires string id and name. Authentication and errors are not specified.
完整示例
{
"openapi": "3.1.1",
"info": {"title": "Illustrative Items API", "version": "0.1.0"},
"paths": {
"/items": {
"get": {
"description": "Draft: authentication and error responses remain unspecified.",
"responses": {
"200": {
"description": "Items",
"content": {"application/json": {"schema": {
"type": "array",
"items": {"type": "object", "required": ["id", "name"], "properties": {
"id": {"type": "string"}, "name": {"type": "string"}
}}
}}}
}
}
}
}
}
}将这份输入载入提示词，再复制到 WebAct 中尝试任务。实际结果可能与示例不同。
决策与问题排查。
OpenAPI 草案应为未记录的端点编造认证方式吗？
记录缺口并索取真实要求。生成的安全方案不能被误认为已经实现的保护。
为什么规范文档有效，生成的客户端却失败？
将架构和状态行为与真实 API 比较。结构有效并不证明文档中的契约符合实现。
此工作流程的参考资料。
使用自己的资料试一试。
将任务提示词中的示例换成你的材料。保留所需条件，再把任务复制到 WebAct。
自定义并复制任务 ↑