AIでAPI仕様書のたたき台を作る方法｜項目と例外を整理する

API仕様書をAIで作るなら、概要文から始めず、operationの目的、HTTP methodとpath、request、response、error、authenticationをひとまとまりで定義します。成功例だけでは実装者が失敗状態を推測することになるため、validation、permission、not found、conflictなど実際に起こる条件も記録します。存在する実装や既存contractを先に確認し、AIが作った仕様をOpenAPI validator、code、testで照合してください。

一つのOperationを契約として書く

API全体を一度に生成すると、resource名、error形式、auth条件の不整合が混ざりやすくなります。最初は一つのoperationを選び、目的と対象resourceを一文で書きます。Pathとmethodは既存命名・versioningルールに合わせ、AIに独自のpath体系を足させません。

表は横にスクロールできます

項目	定義すること	書き漏れの例
Operation purpose	何を取得・作成・変更するか	効果が曖昧
Path / Method	resourceと操作	名称の一貫性がない
Parameters	path/query/header、型、required	空値や範囲が不明
Request Body	schema、nullability、validation	必須と任意が混在
Success	status、media type、response shape	成功時のbody不明
Errors	条件、status、schema、retry可否	失敗の種類を統合
Security	scheme、scope、role、permission	認証と認可が混同
Side effects	保存、通知、外部連携	重複実行時の挙動

OpenAPIはHTTP APIを人と機械が理解できる形で記述する仕様であり、documentation generation、code generation、test等に利用できます。形式的な適合は業務上の意味や実装との一致を保証しません。OpenAPI版、schema dialect、validatorの対応範囲をプロジェクトで確かめます。

RequestとResponseの詳細

各fieldに名前、型、必須か、許容値、format、nullの意味、exampleを付けます。任意fieldの省略と明示nullが違うなら、別々に定義してください。文字数、配列数、pagination、sort、locale、timezoneも用途に必要なら記載します。

Success responseでは返すfield、emptyの表現、created/updatedの区別、header、paginationを定義します。Error responseではmachine-readable code、利用者向けmessage、retry可否、request ID等を既存APIの慣例に合わせます。全HTTP errorを一つの「失敗」にまとめず、callerが適切な対応を選べる粒度にします。

表は横にスクロールできます

条件	API側で決めること	Callerができること
invalid input	field error / code	入力を直す
unauthenticated	認証error contract	再認証
forbidden	permission不足を示す	権限依頼
resource missing	not found表現	IDやURLを確認
duplicate / conflict	idempotency、競合条件	最新状態を読む
dependency failure	timeout、retry policy	必要時に再試行

表は一般的な切り分け例です。status codeやerror bodyは既存systemとHTTP semanticsに合わせ、慣例だからという理由だけで決めないでください。副作用がある操作のretryは、重複作成や課金を起こさないか確認してから仕様化します。

Securityと情報の取り扱い

認証方式、authorization scope、tenant境界、機密field、個人情報をどこで検証するか記載します。API keyやtokenをrequest例へ実値で書かず、placeholderを使います。Logに残すrequest/response項目、masking、保存期間も既存security ruleへ合わせます。OpenAPIのsecurity declarationはmechanismを記述しますが、operationが実際に権限検証を実装している証明ではありません。

Request bodyに秘密情報が含まれる場合、error responseへ値をそのまま返さないことを明記します。File uploadならcontent type、size、scanや保管条件、external連携ならtimeoutと部分失敗、webhookなら署名検証や重複eventの扱いなど、scope固有の条件を確認します。

AIでDraftする手順

1. API実装、既存仕様、schema、test、認証方式を集める。

2. 変更対象のoperationを一つ選ぶ。

3. 入力情報から確定済み事項と未決事項を分ける。

4. AIに既存形式へ合わせたOperation Draftを作らせる。

5. 未決のstatus、error、permission、副作用を勝手に埋めていないか確認する。

6. OpenAPI parser / linterで構造を検証し、生成結果を実装と照合する。

7. contract testやintegration testの必要性を担当者と判断する。

8. 承認後に仕様書versionとownerを記録する。

OpenAPI validatorが成功しても、server codeが同じ意味で動くとは限りません。例のrequestを実環境へ送るときはsandboxかtest環境を使い、production dataやexternal side effectを発生させないようにします。

Prompt例

既存API contract：[仕様書や実装を参照]

Operation purpose：[一文]

Path / Method：[既存規則内の値]

Request fields：[型、required、範囲、例]

Success：[現行contractに沿うresponse]

Known errors：[確認済みの条件だけ]

Authentication / Authorization：[実装済み方式]

Side effects / retry：[重複実行と再試行の扱い]

未確認事項：[AIが補完せず質問にする]

出力：OpenAPI形式のDraftと、曖昧な点の一覧。

未確認のstatus、schema、permissionを創作しない。

Validation checklist

• OpenAPI versionとvalidatorの対応が合っている。

• operationのsummary/descriptionが利用者の目的を示す。

• operationId、path、parameter名が既存規則に一致する。

• request/response schemaにrequired、nullability、exampleが含まれる。

• error responseとsecurity schemeが実装のcontractと一致する。

• reference先、media type、headerが解決できる。

• secret、実user data、内部hostを公開exampleへ含めていない。

• 実装、contract test、generated clientと差がない。

仕様書にしかない挙動が見つかったら、AIの文章で埋めずAPI ownerへ確認します。逆に実装にしかないerrorやfieldがあれば、仕様が古いのか実装がずれているのかを判定し、勝手に正本を選びません。

AIものさしの判断

APIのたたき台は、存在するcontractを読みやすく構造化する作業に向きます。path、error semantics、認可、retry、schemaの決定をAIへ委任しないでください。validator、実装、testの三つが一致し、ownerが未決事項を解消した後に初めて「仕様書として使える」状態と判断します。

Exampleを意味の検査に使う

Exampleは見栄えだけの値ではなく、schemaに対する使い方の検査です。正常例が必須fieldを含むか、error例が該当条件で起こるか、個人情報やtokenが含まれないかを確認します。Exampleが実装へ送れる形式なら、sandboxで送信し、response shapeとstatusの一致をtestします。仕様にしかないsample responseを成功例と誤認させないよう、架空例か実行済み例かを明記します。

表は横にスクロールできます

Example kind	用意する値	検証
minimum valid	requiredだけを含む	最小成功条件
full valid	optionalを含む	拡張field
invalid	型または範囲違反	validation error
unauthorized	認証情報なし	auth response
conflict	競合状態	retryや再取得

APIのerror bodyやstatusは既存契約が正本です。例表で一般的な値を挙げても、実APIの返却値として文書へ貼らず、実装・testで確定します。

変更の互換性を確認する

既存利用者が使うfield名、型、enum、required条件を変えると、clientやstored dataが影響を受けます。追加fieldがbackward compatibleか、既存clientが未知fieldを許すか、deprecated fieldをいつ外すかを確認します。Versioningやmigrationを導入する必要がある場合は、API ownerの既存方針へ従い、AIが独自のversionを決めないようにします。

仕様書を公開した日、対象API version、実装releaseを並べると、どの実装を説明しているか追いやすくなります。仕様書とserverが違うままの場合は、文書を整形して終わりにせず、矛盾をblockerとして扱う選択肢も必要です。