はじめに
- AI駆動開発で、API設計書を記述する方法をまとめてみました。OpenAPI Specificationで記述します。
- 今までツールを使ってOpenAPI Specificationを記述していましたが、生成AIが書いてくれたら楽だよねと考え、運用などについてまとめます。
- AI駆動開発で設計書を全体的にmarkdownに移行したので、そのついでにツールからAIへ移行しました。
OpenAPI Specificationとは
- OpenAPI Specification（OAS）は、REST APIを記述するための標準フォーマットです。YAML（またはJSON）で記述し、エンドポイント・リクエスト・レスポンスの構造を人間と機械の両方が読める形で定義できます。
- AI駆動開発においては、この仕様をAIが理解・生成・修正できる形式で管理することが重要です。OASのYAMLは構造が一貫しているため、AIとの相性が非常に良いフォーマットです。
API-First設計
- API-Firstを行うことで、フロントエンドとバックエンドにおいて、厳格に曖昧さのなく整合性を保つことができ、AIの曖昧さを完全に排除できる。
- 実装前に仕様を確定することで、フロントエンドとバックエンドの並行開発が可能になります。
- APIの仕様修正の同期をフロントエンド、バックエンドに対し整合性を保てます。
ドキュメント自動生成、コード生成
- 仕様書から Swagger UI や Redoc によるインタラクティブなドキュメントを生成できます。
- サーバースタブやクライアントSDKを自動生成するツールが豊富にあります。
- リクエストやレスポンスのスキーマをそれぞれの言語のクラス出力できます。言語レベルで整合性の担保を行うことができます。
- ちなみに、フロントエンドは、
OrvalでSWRとzodを生成しています。バックエンドはOpenAPI Generatorで生成しています。
バリデーション
- リクエスト・レスポンスのスキーマを厳格に定義することで、実装の品質担保に活用できます。
- バリデーションもコード生成により、作成することができます。ツールで行うことができ、ミスはありません。
運用のポイント
- OpeanAPIのymlはいろいろ書き出すと、1万行は余裕で超えます。分割したファイルをAIで編集することが有効です。分割したものをツールで結合してもらい、既存の運用が行なえます。
- 生成AIで強大なファイルを修正するのが、難しいと思います。
- 分割と結合を行うことで生成AIとの入出力が減り、効果的に修正を行えます。
-
npx @redocly/cliを使います。- 分割と、結合、lint、プレビュー、HTML生成が行えます。
-
npx @redocly/cliの分割と、結合、lint、プレビュー、HTML生成のバッチファイルをそれぞれ記述しておきます。
AIの指示方法
作成ルール
- API設計書の元となる情報を指定しておきます。画面設計書、テーブル定義、機能設計書などを指定しておきます。
- こう書いてほしいと記述内容や方法も指定します。
- その他、プロジェクトなどのお決まりごとも指定します。
- 作成後はlintや結合など行うように指示しておきます。
レビューコマンド
- 現時点では、ある程度まとまった段階でレビューできるように、手作業で直接実行するようにしています。
- 少し修正するたびに実行されると、時間がかかりすぎすので。
- 表記や命名、用語の揺れの検出
- 名称に対する同じ形式、バリデーション、説明などの統一化
- 元の情報との整合性の検出
- バリデーションなど記述漏れの検出
- その他、業務的条件などのチェック
修正コマンド
- API設計書の記述段階によりコマンドを分けました。いろいろな場面を想定した記述の指示を作りました。
- API一覧の作成と修正を記述しました。追加とか削除とか変更とかいろいろ変わります。
- APIそれぞれのリクエスト、レスポンスなどのスキーマ定義用で実行します。ここもあれこれ修正が入ります。
- APIの説明記述。プロジェクトによって色々記述したいことはあるので。記述内容はバックエンドの実装のネタになるレベルで書いてもらいました。
- 分割したものを修正するように、元とすることを指示する。巨大ファイルを読み込みや編集することを回避する。
運用方法
- AIに指示をし編集してもらい、API設計のプレビューで修正結果を確認します。
- 作成できたら、レビューを行って、修正してもらう。
- 結合されたYMLをコード生成などに送る。
- 人のためにHTMLなどで、設計書をツールで生成する。
- 分割もできるので、他のツールで修正したものを適用するルートも確立しています。また初期配置など使用してください。
感想
- AIを使ってみて、たまにポカしますが、概ねいい感じでに動いてます。
- プレビューとツールでは、細かいところでツールのほうが、確認しやすいところはある。
- 全体の用語や記述の統一をプロンプト一つで行ってくれるのはありがたい。
- lint以上のチェックとその修正、レビューを行ってくれます。
- 画面設計書から項目も簡単に定義してくれます。画面設計書もそれに合った記述内容で更にさらに良い結果になります。
- どのような設計方針、設計ポイントなどの設計ノウハウを与えないと、当然ながらイメージとかけ離れたもにになってしまいます。まだまだ精度を高める必要があります。