コードからAPI仕様書を作成する

APIドキュメントの作成をChatGPTに依頼する際、最も頻繁に起きるトラブルは「コードに存在しないパラメータが表に入り込むこと」です。コードだけをそのまま渡すと、AIは一般的なRESTの慣例から page、limit、sort といった項目を勝手に補完してしまいます。そのドキュメントを見て開発した人は、存在しないパラメータを送信して400エラーに遭遇することになります。

課題の段落で「コードに実際に記述されているエンドポイントのみ」と釘を刺しているのはそのためです。抽出する項目をパス・メソッド・リクエスト・レスポンス・エラーと列挙したのも同じ目的です。明確な項目リストを与えないと、AIはパスと1行の説明だけを書いて、肝心なリクエストボディの構造を省略してしまいます。エラーレスポンスを項目に含めているのも同様の理由です。正常系のレスポンスしか書かれていないドキュメントは、フロントエンドの実装においてほとんど役に立ちません。

冒頭でフレームワークを指定するのは、ルーティング規約やデコレーターがフレームワークごとに異なるためです。@RequestParam がクエリなのかボディなのか、req.params がパス変数なのかは、フレームワークが分かって初めて判断できます。形式に「位置(パス/クエリ/ボディ)」の列を含めたのも、この区別を表に残すためです。

制約の「コードから確認不可」と「(推測)」の表記指定は、API仕様書の自動生成に不可欠な安全装置です。空欄のままにしておくとAIは埋めようとしますが、書くべきテキストが決まっていれば、分からないものを分からないと書くようになります。コードを """ で囲んでいるのは、コメントに含まれる「TODO: この部分は無視」といった文章が指示として誤認されるのを防ぐためです。

表は出力されますが、コードにない page や limit などのパラメータが混ざり、必須か否かやパラメータの位置（クエリ/ボディ等）が抜けているため、そのまま使うとAPI呼び出しに失敗します。エラーレスポンスも省略されがちで、結局フロントエンド開発者がエラー時の挙動を一つひとつ確認する羽目になります。複数のエンドポイントを一度に渡すとフォーマットもバラバラになり、後からドキュメントを統合するのも困難です。