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 にコピーします。
タスクを調整してコピー ↑