API仕様書から説明文を作るAIプロンプトテンプレート
API仕様書をそのまま渡して「わかりやすく説明して」と頼むと、読みやすい文章にはなっても、開発者が知りたい条件や営業・CSが説明に使いたい注意点が抜けやすくなります。
このテンプレートは、OpenAPI などのAPI仕様、エンドポイント一覧、リクエスト・レスポンス例をもとに、社内共有や外部向けドキュメントに使える説明文を作るためのものです。対象は、APIを読む機会はあるけれど、毎回文章化に時間がかかる開発者、PdM、テクニカルライター、CS担当者です。
- 使う場面: API仕様書から説明文、利用手順、注意点を作る
- 入力するもの: エンドポイント、認証方式、パラメータ、レスポンス例、制約
- 出力形式: 見出し付きの説明文、表、確認チェックリスト
- 向いているAI: ChatGPT、Claude、Geminiなどの汎用LLM
- 注意点: 機密情報、APIキー、個人情報は伏せてから入力する
ここがポイント: AIには「説明して」ではなく、「誰に向けて、何を判断できる説明にするか」まで指定します。
何に使うテンプレートか
このテンプレートの目的は、API仕様を読める文章にすることではなく、読み手が次の行動を決められる説明文にすることです。
API仕様書には、メソッド、URL、パラメータ、ステータスコード、レスポンス例などが並びます。これは実装者には必要な情報ですが、社内の別チームや初めてAPIを触る人には、次のような疑問が残りがちです。
- このAPIは何をするためのものか
- どのタイミングで呼び出すのか
- 必須パラメータと任意パラメータは何か
- 成功時と失敗時に何が返るのか
- 実装前に確認すべき制約は何か
OpenAPI Specification はHTTP APIの振る舞いを記述する仕様として使われますが、仕様そのものは説明文ではありません。だからこそ、AIに渡すときは「仕様を読んで文章にする」だけでなく、読者別に使える形へ変換する指示が必要です。
完成イメージ
この記事のテンプレートを使うと、次のような出力を狙えます。
- 開発者向け: 実装時に見るエンドポイント説明
- 非エンジニア向け: APIで何ができるかを伝える概要文
- CS・営業向け: 顧客説明に使える注意点つきの説明
- レビュー向け: 仕様の不足や確認事項の洗い出し
単なる要約ではなく、「説明文」「入力項目」「注意点」「確認事項」を分けて出すのがコツです。
コピペ用プロンプトテンプレート
まずは、API仕様書を説明文に変える基本テンプレートです。{} の部分を自分の案件に合わせて書き換えてください。
あなたはAPIドキュメントを作成するテクニカルライターです。
以下のAPI仕様をもとに、{想定読者}が理解しやすい説明文を作成してください。
# 目的
{このAPIを説明する目的。例: 社内開発者向けの実装ガイドに載せる / CSが顧客説明に使う / 外部開発者向けドキュメントを作る}
# 想定読者
{読者の職種・知識レベル。例: Web APIの基礎は知っている開発者 / APIに詳しくない営業担当 / 初めて連携する外部パートナー}
# API仕様
{ここにAPI仕様、OpenAPIの該当部分、エンドポイント一覧、リクエスト例、レスポンス例を貼る}
# 出力してほしい内容
1. APIの概要を3〜5文で説明
2. 使う場面を箇条書きで説明
3. エンドポイント、HTTPメソッド、認証方式を整理
4. 必須パラメータと任意パラメータを表で整理
5. 成功時レスポンスの読み方を説明
6. 主なエラーと利用者が取るべき対応を説明
7. 実装前に確認すべき点をチェックリスト化
# 書き方の条件
- 仕様に書かれていないことは推測で断定しない
- 専門用語を使う場合は短く補足する
- APIキー、トークン、個人情報らしき値が含まれる場合は伏せ字にする
- 不明点は「確認が必要な点」として最後に分ける
- 出力はMarkdown形式にする
この形にしておくと、AIは「概要だけを書く」のではなく、説明文、表、エラー対応、確認事項まで分けて出しやすくなります。
入力時に変える部分
変えるべき場所は多く見えますが、毎回すべてを作り込む必要はありません。最低限、読者・目的・仕様本文の3つを入れるだけで出力はかなり安定します。
必ず変える項目
{想定読者}: 読む人の前提知識を指定する{このAPIを説明する目的}: 実装用、営業説明用、社内共有用などを指定する{API仕様}: エンドポイント、パラメータ、レスポンス例を貼る
特に大事なのは想定読者です。同じAPIでも、開発者向けなら「リクエスト形式」「認証」「エラー処理」が中心になります。営業・CS向けなら「何ができるか」「どこまで対応できるか」「顧客に説明するときの注意点」が中心です。
できれば入れたい項目
- APIの利用シーン
- 連携先システム名を伏せた概要
- 認証方式
- レート制限や利用上限
- サンプルリクエスト
- サンプルレスポンス
- 既知の制約や対象外の操作
レート制限や対象外の操作は、説明文の品質を大きく左右します。たとえば「1分あたり何回まで呼び出せるか」「削除APIは物理削除か論理削除か」のような情報は、実装判断に直結します。
固定しておくとよい条件
毎回変えずに固定してよい条件もあります。
- 仕様にない情報は補わない
- 不明点は本文に混ぜず、最後に「確認が必要な点」として出す
- セキュリティ上の秘密情報は伏せ字にする
- 読み手が次に確認すべき行動まで書く
AIは自然な文章を作るのが得意ですが、仕様書にない背景まで補ってしまうことがあります。API説明では、その自然さが危険になる場合があります。断定してよい情報と、確認が必要な情報を分ける指示は固定しておきましょう。
出力形式を指定する追加プロンプト
説明文だけでなく、利用目的に合わせて出力形式を変えると使いやすくなります。
社内共有向け
上記のAPI仕様を、社内共有用の説明文にしてください。
出力形式:
- 概要
- できること
- できないこと・制約
- 利用時の注意点
- 関係者が確認すべきこと
読み手は、開発者、CS、営業、企画担当が混在しています。
専門用語は必要最小限にし、APIに詳しくない人にも意味が伝わるようにしてください。
社内共有向けでは、細かいパラメータ説明よりも「何に使えるか」「誰が確認すべきか」が重要です。チーム横断の文章では、実装詳細を詰め込みすぎると読まれにくくなります。
外部開発者向け
上記のAPI仕様を、外部開発者向けドキュメントの説明文にしてください。
出力形式:
1. APIの概要
2. 認証と前提条件
3. リクエストパラメータ
4. レスポンス項目
5. エラーレスポンス
6. 実装時の注意点
7. サンプル説明文
仕様に書かれていない挙動は断定せず、「仕様上は確認できない」と明記してください。
外部開発者向けでは、曖昧な表現を避けます。「通常」「基本的に」「おそらく」といった言葉が多い説明は、実装時の判断材料になりません。
顧客説明向け
上記のAPI仕様を、顧客説明に使える文章へ言い換えてください。
出力形式:
- このAPIでできること
- 利用開始前に必要な準備
- 顧客側で確認してほしい情報
- 制約や注意点
- 技術担当者へ引き継ぐべき確認事項
条件:
- HTTPメソッドやJSONなどの技術用語は、必要な場合だけ短く説明する
- 営業資料のように過度に魅力的な表現にしない
- 仕様にない保証や性能を追加しない
顧客説明向けでは、技術的に正しいだけでは足りません。顧客が準備する情報、社内で技術担当へ渡すべき確認事項まで出すと、実務で使いやすくなります。
NG例と改善例
API説明文のプロンプトでよくある失敗は、AIに役割と読者を渡していないことです。
NG例
このAPI仕様をわかりやすく説明してください。
この指示でも文章は出ます。ただし、誰にとってわかりやすいのかが決まっていません。開発者向けの説明なのか、営業向けの説明なのか、外部パートナー向けなのかが曖昧です。
結果として、次のような出力になりがちです。
- 概要だけで実装条件が抜ける
- パラメータ説明が浅い
- エラー時の対応が書かれない
- 仕様にない便利な使い方を補ってしまう
- 不明点と確定事項が混ざる
改善例
あなたはAPIドキュメントを作成する担当者です。
以下のAPI仕様を、外部開発者が実装前に確認できる説明文にしてください。
必ず含める内容:
- APIの目的
- 呼び出しタイミング
- 認証方式
- 必須パラメータ
- 任意パラメータ
- 成功時レスポンス
- エラー時の対応
- 仕様からは判断できない確認事項
条件:
- 仕様に書かれていないことは断定しない
- Markdownで出力する
- 最後にレビュー担当者向けチェックリストを付ける
API仕様:
{API仕様を貼る}
改善後のポイントは、読者を「外部開発者」に絞り、出力に含める項目を明示している点です。さらに「仕様からは判断できない確認事項」を分けることで、AIの推測を本文に混ぜにくくしています。
出力を安定させるコツ
API仕様書を扱うときは、文章のうまさよりも、情報の抜け漏れと断定ミスを減らすことが重要です。
1. 仕様本文と依頼文を分ける
仕様を貼るときは、依頼文と仕様本文を見出しで分けます。
# 依頼
以下のAPI仕様を説明文にしてください。
# API仕様
...
この区切りがないと、AIが仕様内のコメントやサンプル値を指示文の一部として扱うことがあります。長いOpenAPI断片やJSONを貼るときほど、境界をはっきりさせてください。
2. 「不明点」を出力に含める
仕様書には、重要なのに書かれていない情報があります。たとえば次のような項目です。
- 認証トークンの有効期限
- レート制限
- タイムアウト時の扱い
- リトライしてよい条件
- エラーコードごとの復旧方法
- 破壊的操作の取り消し可否
これらをAIに埋めさせるのではなく、「確認が必要な点」として出させます。API説明文では、わからないことをわからないまま分離するほうが実務では安全です。
3. サンプル値を本物として扱わせない
API仕様には、user@example.com や 12345 のようなサンプル値が含まれます。AIがそれを実データのように説明してしまうと、誤解のもとになります。
追加で次の一文を入れておくと安定します。
サンプル値は実データではなく例として扱い、説明文では「例」と明記してください。
特に個人情報、顧客ID、注文番号、アクセストークンが含まれる場合は、AIに入力する前に伏せ字へ置き換えてください。
4. レビュー観点を最後に出す
API説明文は、AIの出力をそのまま公開するのではなく、人が確認してから使います。最後にレビュー観点を出させると、確認作業が短くなります。
最後に、公開前レビューで確認すべき項目を5〜8個のチェックリストで出してください。
チェックリストには、認証、必須項目、エラー、制約、機密情報の有無を含めるとよいです。
活用例：1つの仕様から3種類の説明文を作る
同じAPI仕様でも、読み手によって説明の形は変わります。1回で全員向けの文章を作るより、用途別に出し分けるほうが実務では使いやすくなります。
開発者向け
このAPI仕様を、実装担当者向けに説明してください。
重点は、リクエスト形式、必須パラメータ、レスポンス項目、エラー時の分岐、リトライ可否です。
最後に、実装前に仕様担当へ確認すべき質問を出してください。
開発者向けでは、判断に必要な項目を細かく出します。特にエラー時の分岐とリトライ可否は、後から不具合になりやすい部分です。
企画・CS向け
このAPI仕様を、企画担当とCS担当が読める説明文にしてください。
重点は、このAPIで実現できる業務、顧客に案内できること、案内時に注意すべき制約です。
技術用語は必要な場合だけ使い、短い補足を付けてください。
企画・CS向けでは、実装手順よりも業務上の意味を重視します。「このAPIで何ができるか」と「何は約束できないか」を分けると、顧客説明に転用しやすくなります。
レビュー担当向け
このAPI仕様をレビューし、説明文にする前に不足している情報を洗い出してください。
出力形式:
- 仕様から読み取れること
- 仕様から判断できないこと
- 公開前に確認すべき質問
- 説明文に入れるべき注意書き
レビュー担当向けでは、文章化よりも不足情報の発見が目的です。公開ドキュメントを作る前にこのプロンプトを通すと、曖昧な仕様を早い段階で見つけやすくなります。
モデルを使うときの前提
2026年7月時点では、ChatGPT、Claude、Geminiのような汎用LLMはいずれも、長い仕様文の整理や説明文の下書きに使えます。ただし、サービスごとの画面、入力上限、ファイル添付、社内データの扱いは契約や設定で変わります。
使う前に確認したいのは、モデル名そのものより次の点です。
- 会社のルール上、API仕様を入力してよい環境か
- 機密情報や個人情報を除外できているか
- 長い仕様を分割しても文脈が保てるか
- 出力を人がレビューする工程があるか
- 公式仕様とAIの文章に矛盾がないか
OpenAI、Anthropic、Googleはいずれもプロンプト作成の公式ガイドを公開しています。共通して使える考え方は、目的、文脈、制約、出力形式を具体的に渡すことです。API説明文では、この4点に加えて「仕様にないことを断定しない」を必ず入れてください。
仕上げチェックリスト
最後に、AIが作ったAPI説明文を公開・共有する前の確認リストです。
- APIの目的が最初に書かれている
- 読者に合った説明の深さになっている
- HTTPメソッド、URL、認証方式が正しい
- 必須パラメータと任意パラメータが混ざっていない
- レスポンス例の説明が仕様と一致している
- エラー時の対応を勝手に補っていない
- レート制限や対象外操作が必要に応じて書かれている
- APIキー、トークン、個人情報が残っていない
- 不明点が本文ではなく「確認が必要な点」に分けられている
API仕様書の説明文づくりで一番避けたいのは、読みやすいけれど根拠が薄い文章です。AIには下書きと整理を任せ、最終判断は仕様の管理者、開発担当、セキュリティ担当が確認する。この分担を固定しておくと、説明文の作成スピードを上げながら、公開前の事故も減らせます。