🚀 Gemini CLIでAPI仕様書を自動生成してみた！プロンプト作成のコツとCopilotとの比較
🎯 はじめに
私が開発・保守を担当している「XD.GROWTH」では、各種ドキュメントをExcelやWordで作成していました。しかし、新機能追加や仕様変更時のドキュメント更新に かなりの時間 がかかっています。
この問題を解決するため、生成AIを活用して以下を目指すことにしました。
- ✅ ソースコード解析から自動でAPI仕様書を生成
- ✅ Markdown形式で出力してGitで差分管理可能に
まずは API仕様書の自動生成 にチャレンジし、実際に試した結果を 使用したプロンプトを中心に まとめ、さらに、GitHub Copilot Chat と Gemini CLI を比較し、 どちらが実用的か？ を検証しました。
💻 動作環境と前提条件
| 項目 | 内容 |
|---|---|
| OS | Windows 10 + WSL2（Ubuntu） |
| エディタ | VS Code |
| プラグイン | GitHub Copilot Chat |
| 生成AI CLI | Gemini CLI |
GitHub Copilot Chatの設定
- モード : Ask
- AIモデル : Claude Sonnet 4
🔍 まずはCopilotでやってみた
既にVS Codeに導入済のGitHub Copilot Chatで、API仕様書を生成してみることにしました。
１から作るという状態でしたので、まずはAPI仕様書のひな形を作ることにしました。
ひな形作成には以下のプロンプトを実行しました。
REST APIのAPI仕様書を作成しようと考えていますが、どのような項目が必要でしょうか？
ひな形をマークダウン形式でダウンロードできる形で提供してください。
生成するひな形ですが以下の点を考慮してください。
- エンドポイント一覧は、リクエストメソッド、URI、説明などの項目で構成される表形式にしてください。
- APIの詳細には処理概要を項目として設けてください。数行の箇条書きで構成されることを想定します。
- 表形式の表記は前後に空行が無いと表示崩れが発生する場合があります。
- 複数行のコード表記は前後に空行が無いと表示崩れが発生する場合があります。
これにより、以下のようなAPI仕様書サンプルが得られました。（抜粋）
API仕様書のサンプル
# API仕様書
## 概要
### API概要
- **API名**: [API名を記載]
- **バージョン**: [APIのバージョン(v1.0など)]
- **説明**: [APIの目的・機能概要を記載]
- **ベースURL**: https://api.example.com/v1
### 認証方式
- **認証タイプ**: Bearer Token / API Key / OAuth2.0 等
- **ヘッダー例**: Authorization: Bearer {access_token}
## 共通仕様
#### HTTPステータスコード
| ステータスコード | 説明 |
|---|---|
| 200 | 正常処理 |
| 201 | 作成成功 |
| 400 | リクエストエラー |
| 401 | 認証エラー |
| 403 | 権限エラー |
| 404 | リソースが見つからない |
| 500 | サーバーエラー |
#### レスポンス形式
- **Content-Type**: `application/json`
- **文字エンコーディング**: UTF-8
## エンドポイント一覧
| メソッド | URI | 説明 |
| --- | --- | --- |
| GET | /api/users | ユーザー一覧取得 |
| POST | /api/users | ユーザー作成 |
---
## API詳細
### 1. ユーザー一覧取得
#### 基本情報
- **メソッド**: GET
- **エンドポイント**: /api/users
- **説明**: ユーザー一覧を取得する
#### 処理概要
#### リクエスト
##### パスパラメータ
##### クエリパラメータ
| パラメータ名 | 型 | 必須 | 説明 | デフォルト値 | 例 |
|---|---|---|---|---|---|
| page | integer | ○ | ページ番号 | 1 | 1 |
| per_page | integer | × | 1ページあたりの件数 | 20 | 20 |
| search | string | × | 検索キーワード | - | "田中" |
##### リクエストヘッダー
| ヘッダー名 | 必須 | 説明 | 例 |
|---|---|---|---|
| Authorization | ○ | 認証トークン | Bearer abc123... |
| Content-Type | ○ | リクエスト形式 | application/json |
##### リクエストボディ
#### レスポンス
##### 成功時（200 OK）
##### エラー時
私は生成した「API仕様書のサンプル」で項目は十分だと思いましたが、過不足や気になる点があるようでしたら、修正を依頼してみてください。
次に「XD.GROWTH フォーム - 利用者機能」のAPI仕様書の生成を試みました。
何度もやり取りを重ねてAPI仕様書を生成しました。この際に指定したプロンプトの要約は以下の通りです。
- 以下を指定して、ソースコードを解析しAPI仕様書の生成を依頼
- 参照するディレクトリ（ワークスペースからの相対パス）を指定
- 開発言語、使用しているフレームワーク、RDBMS
- アウトプットはマークダウン形式で、フォーマットのサンプルをコンテキストに指定- APIの概要はソースコードから取得するのは困難なので以下を概要情報として指定
- API名: XD.GROWTH フォーム - 利用者機能
- バージョン: v1.0
- 説明: XD.GROWTHで作成したフォームの表示・入力で利用するAPI
- ベースURL:https://form.xdata.jp
結果：それなりのAPI仕様書が出力されましたが、いくつかの課題も見えてきました。
❗ 課題
- ソースコードを正確に反映できない（推測が混じる）
- ローカルでファイルを保存できない
- CLIコマンドやDBアクセスができないため、情報収集に制約あり
⚡ Gemini CLIで再チャレンジ
⚠️ 注意事項 ※重要※
- 無償版のGemini CLIをデフォルトの設定のまま使用すると、入力したプロンプトやソースコードが学習データとして利用されます。
- 学習データとして利用されないようにするには、後述の「 セキュリティ配慮について 」を参照してください。
✅ Gemini CLIを選んだ理由
- ローカルでコマンド実行＆ファイル操作が可能
- 無償枠で十分利用可能（1,000リクエスト/日、100万トークン）
- 広いコンテキストウィンドウ（大規模コードベースに有利）
※Gemini CLIの無料枠は2025/08/28での内容です
🛠 インストール＆セットアップ
参考記事: こちら
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install --lts
npm install -g @google/gemini-cli
セットアップ開始:
gemini
Googleアカウントで認証すればOKです。
🖋 プロンプトの指定方法（ファイル指定）
API仕様書のフォーマットはCopilotで生成したもので問題ないので、そのまま利用します。
Gemini CLIでは 長文プロンプトを直接入力するのは非現実的 なので、以下のように テキストファイルで指定 します。
次のファイルをプロンプトとして実施してください。{path-to-prompt-file}
プロンプトファイルの例（抜粋）:
このリポジトリはWebアプリケーションの1機能です。
- 開発言語 : {Java / PHP / TypeScriptなど}
- フレームワーク : {使用中のフレームワーク}
- データベース : PostgreSQL
で構成されています。
実装コードを解析してAPI仕様書をマークダウン形式で作成してください。
フォーマットのサンプル : {api_document_sample.md}
作成するファイル : {api_document.md}
API仕様書の基本情報については以下のとおりです
- タイトル : XD.GROWTH フォーム - 利用者機能 API仕様書
- API名 : XD.GROWTH フォーム - 利用者機能
- バージョン: v1.0
- 説明 : XD.GROWTHで作成したフォームの表示・入力で利用するAPI
- ベースURL : https://form.xdata.jp
以下について、必要なら確認をしてください。
1. API仕様書を作成するにあたって不足している情報はありますか？
2. データベースへのアクセスも必要になりますか？
結果：手直しをしなくても使えるレベルの ソースコードを正しく解析した API仕様書が出力されました！
🔒 セキュリティ配慮について
生成AIにプライベートなソースコードを解析してもらうにあたって、以下のセキュリティリスクが考えられます。
- 学習データとして利用されないか？
- APIキーなど重要な情報が流出してしまわないか？
Gemini CLIの無償版だと対話プロンプトにて以下を入力すると、プライバシーポリシーが表示されます。
/privacy
●表示されるプライバシーポリシー
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ │
│ │
│ Gemini Code Assist for Individuals Privacy Notice │
│ │
│ │
│ This notice and our Privacy Policy[1] describe how Gemini Code Assist handles your data. Please read them carefully. │
│ │
│ │
│ When you use Gemini Code Assist for individuals with Gemini CLI, Google collects your prompts, related code, generated │
│ output, code edits, related feature usage information, and your feedback to provide, improve, and develop Google products│
│ and services and machine learning technologies. │
│ │
│ │
│ To help with quality and improve our products (such as generative machine-learning models), human reviewers may read, │
│ annotate, and process the data collected above. We take steps to protect your privacy as part of this process. This │
│ includes disconnecting the data from your Google Account before reviewers see or annotate it, and storing those │
│ disconnected copies for up to 18 months. Please don't submit confidential information or any data you wouldn't want a │
│ reviewer to see or Google to use to improve our products, services and machine-learning technologies. │
│ │
│ │
│ Allow Google to use this data to develop and improve our products? │
│ 1. Yes │
│ ● 2. No │
│ │
│ │
│ [1] https://policies.google.com/privacy │
│ │
│ │
│ Press Enter to choose an option and exit. │
│ │
│ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
ここで2. Noを選択することで学習データとして利用されなくなります。
詳しくは、「Gemini CLI の無料利用でも Google の ML モデルの改善に使用されなくする」に説明されています。
但し、以下を注意してください。
- プロンプトにAPIキーなどの重要な情報は指定しない
- 読み込んだデータをどのように利用されるのかについては、利用する生成AIモデルや利用規約の変更などで変わってくるので、データを読み込ます前に データをどう取り扱うのか？ について確認をしておく
✅ Gemini CLIを使ってみた感想
- ドキュメント作成といった作業では Copilotよりも精度が高く、修正不要レベル
- 100万トークンのコンテキストウィンドウが強力
- ローカル実行可能な点が大きなメリット
⚠ 注意点とベストプラクティス
-
起動ディレクトリ配下しか参照できない
- プロンプトや作業用ファイルは専用ディレクトリにまとめる
-
逐次承認を回避するプロンプト
- ローカルのファイルの参照、API毎に生成開始の確認が頻繁に入る場合の回避方法
あなたの作業で必要になる全てのファイルの読み取りを許可します 全てのAPI仕様書を自動生成してください。逐次承認は不要です -
トークン数制限に注意
- 大規模なコードベースでは分割処理が必要な場合がある
- 重要なファイルから優先的に指定することをおすすめします
📊 CopilotとGeminiの比較表（API仕様書を生成する場合）
| 項目 | GitHub Copilot Chat | Gemini CLI |
|---|---|---|
| 生成精度 | 中（推測含む） | 高（コンテキスト広い） |
| 長文プロンプト対応 | △（UI入力制限あり） | 〇（テキストファイル指定可） |
| ローカルファイル参照 | △（ワークスペースや開いたファイルのみ） | 〇（ディレクトリ全体を読み取り可能） |
| コマンド実行 | ✕ | 〇 |
| ファイル保存 | ✕ | 〇 |
| 無償枠の実用性 | △（月に50回のチャットメッセージ） | 〇（１日に1000回のリクエスト） |
| 適用シーン | IDE内での開発支援 （コード生成・デバッグ・リファクタリング） |
大規模データ処理 （ドキュメント生成・自動化タスク） |
※標準機能での比較です。MCPサーバーなどを導入することで対応可能になる項目が変わってきます
💡 プロンプト改善Tips集
以下をプロンプトに含めておくと、より良いアウトプットが望めると思います。
- 「不足情報があれば質問してください」 と書く
- フォーマットサンプルを渡す
- 「実装コードを正確に反映してください」 を強調する
- 段階的生成を防ぐために「すべて一括で生成」と指示
🔮 次に試したいアイデア
- Gemini CLIで データベースER図を自動生成 （近いうちに）
- CI/CDパイプラインに組み込み、自動でAPI仕様書更新 （そのうちに）
- テストコードやモックAPI生成の自動化 （そのうちに）
✅ まとめ
ドキュメント生成では
- Gemini CLIは ローカルで使える強力な生成AIツール
- Copilotよりも 精度・柔軟性ともに優秀
だと感じました。
CopilotはVS Codeとより密に結合しており、開発時のコード補完・生成で威力を発揮するように思います。つまり、用途が違うので比較することが間違っているのかもしれませんが、私の開発環境で用意できる生成AIでは、用途ごとにどちらを使えば良いかが見えたのは良かったと思っています。👍
あと、対話型で細切れにプロンプトを投入するより、まとめて投入した方が精度の高いもができました。プロンプトをまとめると、どうしても長文になりますので、 プロンプトはファイルで運用 することを前提にすることをおすすめします。
本記事を読んでいただきありがとうございました。生成AIでドキュメントを生成する場合の参考になれば嬉しいです。🙌
👍 記事の感想や「もっと良い方法があるよ」「他の生成AIの場合は、、、」などありましたら ぜひコメントをください！