当サイトの記事は編集部が国土交通省・IPA・デジタル庁などの公的機関の情報、規格や業界団体の公開情報を調べて独自に執筆しています。記事内にIT・Webエンジニアの転職サービスへの案内（広告）を含みます。
ほかのシステムとつなぐAPIを作ることになり、『API仕様書を書いておいて』と言われた。でも、どの項目をどこまで書けばいいのか分からない。そんな方も多いはずです。
結論から言うと、API仕様書はAPI1本ごとに「入口」「受け取る物」「返す物」「失敗した時」の4枠を埋めれば、使う側が迷わない文書になります。全APIに共通する決まりは、最初に1か所にまとめておきます。
この記事を読めば、API仕様書の書き方と、テンプレートに入れておく項目が分かります。
API仕様書とは？誰のために書く文書か
API仕様書は、APIを呼び出す側の人が「どこに、何を送れば、何が返ってくるか」を知るための説明書です。作った本人ではなく、使う人の目線で書くのが大事です。
APIは、システムどうしがデータをやり取りするための窓口です。Webを通じて呼び出すものはWebAPIと呼ばれ、その中でもURLと決まった方式で操作するREST APIの形がよく使われています。
API仕様書は、その窓口の使い方をまとめた文書です。画面設計書が人に向けた画面の説明なら、API仕様書はプログラムに向けた窓口の説明、と考えると分かりやすいですよ。
読む人によって知りたいことが違う
『誰が読むのか』を先に決めておくと、書く細かさで迷いません。
| 読む人 | 知りたいこと | 厚く書く所 |
|---|---|---|
| 呼び出す側の開発者 | 送る項目と、返ってくる項目 | 受け取る物・返す物の項目表 |
| テスト担当 | 正しい時と失敗した時の結果 | 失敗した時の一覧 |
| 発注側・連携先の担当 | 何ができるAPIか | APIの一覧と概要 |
| 運用の担当 | 呼び出せる回数や時間帯の決まり | 共通の決まり |
社外の会社に公開するAPIなら、相手は社内の事情を知りません。社内向けより一段ていねいに書いておくと、問い合わせがぐっと減ります。
API1本は4枠で書く
API1本の仕様は「入口（URL・方式）」「受け取る物」「返す物」「失敗した時」の4枠に分けて書きます。特に失敗した時の枠が抜けやすいので、最初から枠を用意しておきます。
API仕様書でありがちなのが、成功した時の返事だけ書いて終わってしまうパターンです。ところが呼び出す側が一番困るのは、うまくいかなかった時なんですよね。
そこで編集部では、API1本を4枠に分けて書く記入表を作ってみました。
| 枠 | 書く中身 | 抜けると起きること |
|---|---|---|
| 入口 | URL（エンドポイント）、方式（取得・登録・更新・削除）、認証のやり方 | 呼び出し方が分からず、試行錯誤になる |
| 受け取る物 | リクエストの項目名、型、必須か、桁数、例 | 送る値の形が人によってばらばらになる |
| 返す物 | レスポンスの項目名、型、毎回返るか、例 | 返事のどこを読めばいいか分からない |
| 失敗した時 | 失敗の種類、ステータスコード、エラーの中身、呼び出す側がすること | エラー時の動きを相手が想像で作る |
枠ごとの記入例
社内の備品貸出システムで「備品を1件取り出すAPI」を作る場面を例にします。どれも編集部の架空の記入例です。
| 枠 | 記入例 |
|---|---|
| 入口 | 方式は取得（GET）。URLは「/items/{備品ID}」。社内で発行したキーを付けて呼び出す |
| 受け取る物 | 備品ID（文字列・必須）。URLの中に入れて渡す |
| 返す物 | 備品ID、備品名、置き場所、貸出中かどうか（真か偽）、返却予定日（貸出中のときだけ） |
| 失敗した時 | 備品IDが見つからない、キーが無い・間違っている、システム側の不具合、の3種類と、それぞれの返事の中身 |
「返却予定日は貸出中のときだけ返る」のように、返ったり返らなかったりする項目は、条件まで書いておくのがポイントです。
REST APIの仕様書の書き方とテンプレート
REST APIの仕様書は「全体の共通事項」「APIの一覧」「API1本ずつの4枠」の3層で作ると、テンプレートとして使い回しやすくなります。
API仕様書のテンプレートを作る時は、1本ずつの説明より先に、共通の決まりを書くページを用意しておきましょう。毎回同じことを書かずに済みますよ。
- 全体の共通事項を書く（つなぎ先のURL、認証、文字コード、日時の書き方）
- 共通のエラーの形を決めて書く
- APIの一覧を作る（番号、名前、方式、URL、概要）
- API1本ずつ、4枠を埋める
- 受け取る物・返す物に、具体的な値の例を添える
- 呼び出す側の人に読んでもらい、分からない所を直す
テンプレートに入れておく項目
| 層 | 項目 | 書き方のコツ |
|---|---|---|
| 共通事項 | つなぎ先、認証、日時や金額の書き方 | 例外がある時は「このAPIだけ」と各ページにも書く |
| 共通事項 | エラーの返し方の形 | エラーの番号と文言の項目名をそろえる |
| APIの一覧 | 番号、名前、方式、URL、概要 | 一覧の番号と各ページの番号を合わせる |
| API1本ずつ | 4枠（入口・受け取る物・返す物・失敗した時） | 項目表には型・必須・例を入れる |
| 変更の記録 | 版、日付、変えた所 | 呼び出す側に影響がある変更を目立たせる |
項目表の書き方
受け取る物・返す物は、項目ごとに1行の表にします。名前・型・必須か・説明・例の5列があれば、ほとんど伝わります。
| 項目名 | 型 | 必須 | 説明 | 例 |
|---|---|---|---|---|
| itemId | 文字列 | 必須 | 備品ID | A0123 |
| name | 文字列 | 必須 | 備品名 | 会議用プロジェクター |
| onLoan | 真偽 | 必須 | 貸出中かどうか | 真 |
| returnDate | 日付 | 任意 | 返却予定日。貸出中のときだけ返る | 予定日の年月日 |
連携の仕様書で「共通部」と「個別部」に分けて書く形を見かけることがあります。共通部が全APIに共通する決まり、個別部がAPI1本ずつの中身と考えると、この3層と同じ考え方ですね。
『項目名は英語？日本語？』と迷ったら、実際に送る名前（英語）と、日本語の説明を両方書いておきましょう。項目の意味がデータベースの項目と同じ時は、テーブル定義書の項目名とそろえておくと、後で追いかけやすくなります。
「詳しくはソースを見てください」と書いてしまうと、社外の相手は確かめようがありません。返す項目が増えた・減った時は、仕様書を先に直してから知らせましょう。
OpenAPI（Swagger）で書く方法
OpenAPI Specification は、APIの仕様を決まった書式で書くための公開された仕様です。この書式で書いておくと、読みやすい説明ページを自動で作ったり、試し呼び出しに使ったりできます。
API仕様書をExcelやWordではなく、OpenAPIの書式で書くやり方も広く使われています。API設計書のことを、Swaggerという呼び方で覚えている方もいますよね。
OpenAPI Initiative のFAQによると、OpenAPI Specification はもともと Swagger Specification として寄贈されたものが元で、2016年に独立したプロジェクトになりました。管理しているのは、2015年11月に Linux Foundation のもとで設立された OpenAPI Initiative です。
2026年10月時点で確認できた最新版は v3.2.1 です。使う版は、OpenAPI Specification の公開ページで確かめておきましょう。
| 比べる点 | ExcelやWordで書く | OpenAPIの書式で書く |
|---|---|---|
| 読める人 | 発注側や業務の担当者も開いて読める | 主に開発者。説明ページを作れば誰でも読める |
| 書き方の自由さ | 決まった形がなく、自由に書ける | 書式が決まっていて、書き漏れに気づきやすい |
| ばらつき | 書く人によって形がばらつきやすい | 形がそろいやすい |
| 使い道 | 打合せの資料にしやすい | 説明ページの自動作成や試し呼び出しに使える |
| 始めやすさ | すぐ始められる | 書式を覚えるまで少し時間がかかる |
OpenAPIで書く時の書き方のコツ
OpenAPIで書く場合も、中身はこの記事の4枠と同じです。入口はパスと方式、受け取る物はパラメータとリクエスト、返す物と失敗した時はレスポンスの欄に書いていきます。
ただ、書式どおりに書いても、項目の「意味」や「いつ返るか」は人が書かないと伝わりません。説明の欄を空にせず、例の値も入れておきましょう。
文書の管理の仕方は、仕様書・設計書をMarkdownで書くも参考になります。
API仕様書でよくある相談
よく見かけるのは「API仕様書とAPIスタブの違い」「仕様書を自動で作れないか」「仕様書と実際の動きが違う時」の3つです。どれも、仕様書を正しい状態に保つことが答えにつながります。
よく見かける相談を、内容をまとめた形で紹介します。
相談1：API仕様書とAPIスタブは何が違う？
API仕様書とAPIスタブがそれぞれ何なのか分からない、という相談です。
API仕様書は、APIの使い方を書いた説明書です。APIスタブは、本物のAPIができる前に、決まった返事だけを返す「代わりの窓口」のことです。呼び出す側は、スタブを相手に先に作り始めることができます。
スタブの返事は仕様書の「返す物」の例から作るので、仕様書の例の値はていねいに書いておくと役立ちますよ。
相談2：ソースから仕様書を自動で作れない？
ソースコードのコメントから、API仕様書を自動で作る方法はないか、という相談もあります。
開発に使う言語や道具によっては、ソースの注釈からOpenAPIの書式の文書を作り出す仕組みがあります。ただ、自動で作れるのは項目と型までです。意味や使い方の注意は、人が書き足す必要があります。
相談3：仕様書どおりに送ったのに動かない
『仕様書のとおりにリクエストを送っているのに、うまくいかない。私がおかしいの？』という相談も見かけます。
こういう時は、仕様書と実際の動きのどちらが正しいかを、作った側に確かめるのが近道です。食い違いが分かったら、仕様書を直して版を上げてもらいましょう。仕様書の直し方と版の付け方は、仕様書の変更管理で紹介しています。
API仕様書を書く経験を仕事に活かす
API仕様書は、システムどうしの約束ごとを決める文書です。相手の立場で考えて書く力は、基本設計や要件定義を任される職場でも評価されやすい力です。
今の職場でAPIの設計を任せてもらえるよう相談してみるのも、立派な一歩です。そのうえで、上流工程の仕事に進みたい方は、求人の仕事内容を比べてみると道が見えてきますよ。
IT・Webエンジニアの転職（PR）
仕様書を書く経験を活かせる職場を探すなら、求人も比べてみる
要件定義や設計を任されるか、発注側か開発側か、扱うシステムや働き方は会社によって大きく違います。担当したい工程や条件から、IT・Webエンジニアの求人を比べてみてください。
無料ITエンジニアの求人を探す求人の条件・待遇は各求人票と応募先の案内でご確認ください。
API仕様書と、画面や機能の設計書との関係は、基本設計書とは？書く項目と書き方や機能仕様書とは？でまとめています。仕様書全体の位置づけは仕様書とは？で確かめられます。
よくある質問
API仕様書には何を書けばいいですか？
全体の共通事項とAPIの一覧を書いたうえで、API1本ずつ「入口」「受け取る物」「返す物」「失敗した時」の4枠を書きます。項目には型・必須・例を添えます。
API仕様書のテンプレートはどう作ればいいですか？
共通事項、APIの一覧、API1本ずつのページ、変更の記録の4つのページを用意しておくと使い回しやすくなります。API1本ずつのページは4枠の形にそろえましょう。
OpenAPIとSwaggerは同じ物ですか？
OpenAPI Specification は、もともと Swagger Specification として寄贈されたものが元になっています。今は OpenAPI Initiative が管理する仕様として公開されています。
API仕様書はExcelとOpenAPIのどちらで書くべきですか？
読む人で選びます。業務の担当者も読むならExcelやWordが読みやすく、開発者どうしで使うならOpenAPIの書式にすると自動化に生かせます。
まとめ
- API仕様書は、呼び出す側の目線で書く使い方の説明書
- API1本は入口・受け取る物・返す物・失敗した時の4枠で書く
- テンプレートは共通事項・一覧・API1本ずつ・変更の記録で作る
- OpenAPI（もとはSwagger）の書式で書くと自動化に生かせる
- 仕様書と動きが違う時は、仕様書を直して版を上げる
コメント