API仕様書・設計書の書き方｜記載項目チェックリストとOpenAPIサンプル・テンプレート

API仕様書やAPI設計書に何をどこまで書けば、受け取った側が問い合わせなしに実装へ入れるのか。拠り所になるのが、デジタル庁が2024年9月30日に改定した「APIテクニカルガイドブック」と、IPAが2025年3月26日に初版を出した「API標準設計ガイド・基礎編」です。記載項目を明示的に列挙している数少ない公的資料です。ただしデジタル庁のガイドは、2026年1月8日のGIF v2.2でGIFの管理対象から外れ、今後の更新や公式説明の対象外になりました。内容が古くなっても直されないため、この記事では両ガイドの項目を突き合わせ、コピーして使える記入テンプレート、lintにかけて確かめたOpenAPI（YAML）のサンプル、認証・エラー・利用制限の書式、提出前のレビュー観点まで項目単位で組み立てます。

まとめ：API仕様書に入れる6項目と、先に決める3つのこと

デジタル庁のAPIテクニカルガイドブックは、表4-2「公開を推奨するドキュメント」でAPI仕様書に含める項目を6つ挙げています。API機能、API利用方法、エラーコード、リクエスト、レスポンス、提供データに関する説明。これが最小セットです。

書き始める前に決めるのは次の3つです。

• 粒度：読み手がその文書だけで最初の1リクエストを送り、返ってきたエラーの意味を自力で説明できるか。満たさない仕様書は、項目が揃っていても問い合わせを生みます。
• 書式：外部公開・SDK配布・モック生成のどれかがあるならOpenAPI（YAML）を正本にし、Excelは項目定義の一覧として出力する。社内の数本の連携ならMarkdownかExcelで足ります。
• 正本：YAMLとExcel、コードとYAMLのどちらを正とするかを表紙に書く。両方を手で直す運用にした時点で、設計書は実装とずれ始めます。

なお両ガイドが参照しているRFCのうち、エラー形式（RFC 7807）・HTTPセマンティクス（RFC 7231）・JSON（RFC 4627）の3本は現行版に置き換わっています。デジタル庁のガイドは今後改定されないので、公的資料の記述をそのまま引き写すと、古い番号を配り続けることになります。

API仕様書・設計書・リファレンスの違いと書き分け

「API仕様書」「API設計書」「APIリファレンス」は、呼称をそろえるより担当範囲を先に決めるほうが早く片付きます。仕様書・設計書・要件定義書の一般的な違いは仕様書と設計書・要件定義書の違いで整理しているので、ここではAPIに固有の線引きだけを扱います。

仕様書と設計書が分かれる基準：読み手と確定タイミング

設計書は作る側の内部文書で、実装前に決めるべき事項を並べたもの。仕様書は使う側に配る外部文書で、確定した振る舞いを記述したものです。線引きは固定ではなく、IPAのAPI標準設計ガイド・基礎編は「API標準設計書」の実体としてOpenAPI Specification（OAS）のYAMLファイルを指しています。表3の構成はInfo、Servers、Paths、components、Security、Tags、externalDocsの7セクションで、設計書であると同時にそのまま公開できる仕様書でもあります。

分けるかどうかは社外公開の有無で決めてください。社外に配るなら、検討経緯や未確定事項を含む設計書とは別に確定分だけを切り出す。社内の1システム間連携で完結するなら、1つの文書にまとめたほうが更新漏れが起きません。リソースの切り方やURIをまだ詰めている段階なら、API設計のリソース定義から版管理までの実装手順を先に固めると文書化の手戻りが減ります。

リファレンスとの違い：自動生成できる範囲と更新責任

APIリファレンスは実装やYAMLから自動生成できる網羅的な一覧を指すのが一般的です。デジタル庁のガイドも「Swagger UIを利用することで、自動でAPI仕様のドキュメントを生成できます」と書く一方、表4-2ではAPI概要・API仕様書・利用規約・利用申請・利用事例の5種類を別建てで推奨しています。

自動生成が肩代わりできるのはリファレンスとコード（SDKならOpenAPI Generatorの対応言語と導入手順）までです。利用申請の手順、利用規約、データの更新タイミングは実装のどこにも書かれていないので、人が書くしかありません。更新責任がツールにあるか人にあるかで分けると、呼称の議論はほぼ消えます。

記載項目チェックリスト：仕様書本体の6項目と概要ドキュメントの12項目

API仕様書本体に載せる6項目と抜けたときの影響

右列は、その項目を落としたときに返ってくる質問の型です。抜けやすいのは「提供データに関する説明」で、デジタル庁のガイドはデータ更新日・提供元・データ内容・更新タイミングを挙げ、「特にデータ提供API」と括弧書きを添えています。夜間バッチで1日1回更新されるデータを、利用側がリアルタイム値と誤解したまま実装するのが典型的な事故です。配布されているテンプレートの多くはこの枠を持たないので、採用するならまず更新日・提供元・更新頻度の行を足してください。

API概要ドキュメントへ切り出す12項目と数値の記入例

デジタル庁のガイドは、次の12項目を「API概要」として仕様書本体とは別の文書にまとめ、利用者の目に留まりやすい場所に置くよう推奨しています。データ内容の概要、提供方式、エンドポイント、OAS定義ファイルの公開場所、リクエストフォーマット形式、レスポンスフォーマット形式、TLS(SSL)サポート、利用申請、認証機能、利用制限、開発者専用サイト、利用規約。

同ガイドの表5-1は内閣府RESAS APIを記入例にしており、利用制限を「呼び出し回数制限あり 上限：2000回/日」、認証機能を「APIキー」、利用規約を「出典明記により、編集・加工も含め自由に利用可」と書いています。「制限あり」で止めず数値まで書く粒度が、真似する価値のある部分です。ただし同じ表には利用制限の行が2つあり、値も二重に記載されています。並びは参考にしても、この重複は持ち込まないでください。

API仕様書のテンプレート：エンドポイント1件分の記入枠

6項目を揃えても、エンドポイントごとの書式がばらつくと、読み手は毎回探し方を変えることになります。実在する行政APIの解説書は1機能あたりの枠を固定しています。国税庁の法人番号システムWeb-APIの解説書のうち第五編（Ver.3.0）は、機能の概要、リクエストのフォーマット、リクエスト例と応答結果のサンプル、一連番号の設定（ソート順）の4つを基本形として検索機能ごとに繰り返し（件数が多い機能には応答結果の分割の節を追加）、エラーコードとHTTPステータスコードは全機能共通の章として末尾に1回だけ置いています。共通部分を機能ごとに書かない、という分け方がそのまま使えます。

Markdownで書く1エンドポイント分のテンプレート

次の枠は、第五編の並びに認証と変更履歴を足したものです。コピーして、エンドポイントの数だけ繰り返してください。認証方式・エラー一覧・利用制限はAPI全体で共通なので、各エンドポイントには書かず共通章への参照だけを置きます。

## GET /api/v1/invoices　請求書一覧の取得

### 概要
- 機能：updated_since 以降に更新された請求書を新しい順に返す
- 提供データ：経理システムの請求書。毎日2時の夜間バッチで更新（日次1回）
- 必要な権限：invoices:read（認証は共通章「2. 認証」を参照）

### リクエスト
| 物理名 | 型と書式 | 必須 | 既定値 | 制約と例 |
|---|---|---|---|---|
| updated_since | string / date-time | 任意 | 制限なし | 2026-08-01T00:00:00+09:00 |
| limit | integer | 任意 | 50 | 1以上100以下 |

### レスポンス（200）
| 物理名 | 型 | null | 説明 |
|---|---|---|---|
| total | integer | 不可 | 条件に合う総件数 |
| next_cursor | string | 可 | 次ページのカーソル。最終ページは null |
| items[].amount | integer | 不可 | 税込金額（円・整数） |

### 例
（実データのリクエスト1件と応答1件をそのまま貼る）

### エラー
共通章「4. エラー一覧」を参照。このAPI固有のもの：なし

### 変更履歴
| 版 | 日付 | 変更内容 | 変更理由 |
|---|---|---|---|
| 1.2.0 | 2026-10-01 | レスポンスに next_cursor を追加 | カーソル方式のページングに対応 |

レスポンス表に「null」の列を置いているのは、レビューで最も手戻りが大きい「nullと項目欠落の区別」を記入時点で決めさせるためです。変更履歴は変更内容と変更理由を別の列にします。理由が併記されていれば、利用側は自分に影響する変更かを1行で判断できます。

パラメータ定義の5列と、書式を先に決める理由

リクエスト表の5列（物理名、型と書式、必須、既定値、制約と例）は、どれか1つが空欄だと質問が来ます。とくに既定値は「省略したら何件返るのか」に直結するので、「制限なし」も含めて必ず書いてください。

書式の標準は表の外で先に決めておくと、各行の記述が短くなります。IPAのガイドは項目定義方針として、日時はformat:date-timeでYYYY-MM-DDTHH:mm:ss+09:00の形、所在地コードはJIS X 0401/0402、文字コードはUTF-8、性別コードや言語コードのように標準化されたコードリストがあればenumで制限する、と採用する標準を列挙しています。国税庁の解説書も項目定義を「別紙1 リソース定義書」として本文から独立させており、同じ項目が複数のエンドポイントに出るなら定義は1箇所に集めたほうが保守できます。

Excelで作るときのシート構成

「API仕様書 サンプル excel」で探している場合、発注側の様式がExcelで決まっていることが多いはずです。Excelは一覧性とフィルタが効くので、行数が増える項目定義に向きます。反面、差分がレビューしづらく、変更履歴がファイル名に埋もれます。国税庁の法人番号システムWeb-APIも、項目定義にあたるリソース定義書だけをPDFとExcelの両形式で配布しています。

右列が「出力」になっていれば、Excelは閲覧用の生成物として扱えます。出力は、pathsとschemasを読んでCSVやExcelを書き出す小さなスクリプトをCIに置き、YAMLが変わるたびに作り直すのが手堅い方法です。Excelを正本にするなら、逆にYAMLをExcelから起こす生成物にして手で触らない。外部に配る・SDKを配るならYAML正本、発注側がExcel様式を指定している業務システム間の連携ならExcel正本、と決めてください。

OpenAPI（YAML）で書くAPI設計書のサンプルとlintでの検証

IPAのガイドに付属していた「法人番号システム WEB-APIサンプル設計書」（YAMLファイル）は、IPAの配布ページで2025年3月28日に公開停止となり、2026年10月19日時点でも「近日中に修正版を公開予定」のままです。そこで、前章のテンプレートを同ガイドの7セクション構成に置き換えたサンプルを用意しました。3.1系で書いており、next_cursorの型を [string, “null”] と配列で書いているのがその目印です（3.0系の nullable: true はこの書き方に置き換わりました）。

7セクションを埋めたOpenAPI 3.1の最小サンプル

openapi: 3.1.2
info:
  title: 請求書API
  version: 1.2.0
  description: |
    提供データ: 請求書の発行状況。更新タイミングは毎日2時の夜間バッチ（日次1回）。
    提供元: 経理システム。変更履歴は CHANGELOG.md を参照。
servers:
  - url: https://api.example.com/api/v1
security:
  - bearerAuth: []
tags:
  - name: invoices
    description: 請求書の参照
paths:
  /invoices:
    get:
      tags: [invoices]
      operationId: listInvoices
      summary: 更新日時で絞り込んだ請求書一覧を返す
      description: updated_since 以降に更新された請求書を新しい順に返す。
      parameters:
        - name: updated_since
          in: query
          required: false
          schema: { type: string, format: date-time }
          example: "2026-08-01T00:00:00+09:00"
        - name: limit
          in: query
          required: false
          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
      responses:
        "200":
          description: 正常
          content:
            application/json:
              schema: { $ref: "#/components/schemas/InvoiceList" }
        "429":
          description: レート制限超過（1分あたり600回）
          headers:
            Retry-After: { schema: { type: integer } }
          content:
            application/problem+json:
              schema: { $ref: "#/components/schemas/Problem" }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer }
  schemas:
    InvoiceList:
      type: object
      required: [total, items]
      properties:
        total: { type: integer }
        next_cursor: { type: [string, "null"] }
        items:
          type: array
          items: { $ref: "#/components/schemas/Invoice" }
    Invoice:
      type: object
      required: [invoice_id, issued_at, amount, currency, status]
      properties:
        invoice_id: { type: string, example: INV-000101 }
        issued_at: { type: string, format: date-time }
        amount: { type: integer, description: 税込金額（円・整数） }
        currency: { type: string, enum: [JPY] }
        status: { type: string, enum: [draft, issued, canceled] }
    Problem:
      type: object
      properties:
        type: { type: string, format: uri }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
        instance: { type: string }
        retry_after_seconds: { type: integer }
externalDocs:
  description: 利用規約と利用申請の手順
  url: https://developer.example.com/terms

デジタル庁の6項目との対応は、API機能がtagsとsummary・description、利用方法がserversとsecurity、リクエストとレスポンスがpathsとcomponents、エラーコードが429のproblem+json、提供データの説明がinfo.descriptionです。OASには「提供データ」専用のフィールドが無いため、書く場所を決めておかないと、YAML化した途端に更新タイミングの記述が消えます。利用規約や利用申請のようにYAMLに収まらない文書は、externalDocsから外へリンクします。

なおこのサンプルは最小構成のため、serversは本番1件だけで、401・403の応答も省いています。後の章のレビュー表では差し戻しに当たるので、実際の設計書では検証環境のURLと、401（トークン無し・期限切れ）と403（権限不足）の応答を足してください。テンプレートの「必要な権限」のようにスコープまでOASに書くなら、securitySchemesを type: oauth2 にし、securityに [invoices:read] を指定します。

SpectralとRedocly CLIにかけた結果と、直した2行

このサンプルの初版にはoperationIdとdescriptionが無く、後の章で示す社内ルール（operation-descriptionをerrorに上げた.spectral.yaml）にかけると落ちていました。2026年10月19日に手元で実行した結果です。

Spectralのerrorはoperation-description、warningはoperation-operationIdです。Redoclyの既定ルールで残る2件は、info.licenseが無いことと、serversがexample.comを指していることへの警告で、サンプルとしては実害がありません。本番の設計書ではlicenseを書き、実在のURLに差し替えると0件になります。先頭行をopenapi: 3.2.1に書き換えても、両ツールとも読み込んで同じ規則で検査しました。

構文として正しいこと（Redoclyのvalid）と、社内の書き方の規則を満たすこと（Spectralの独自ルール）は別の検査です。説明文の無いオペレーションはSwagger UIで一覧にしたときに中身が読めないので、descriptionの必須化は最初に入れる価値があります。

リクエスト例と応答サンプルは実データで1件ずつ

GET /api/v1/invoices?updated_since=2026-08-01T00:00:00%2B09:00&limit=1 HTTP/1.1
Host: api.example.com
Authorization: Bearer {access_token}
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "total": 2,
  "next_cursor": "eyJpZCI6MTAyfQ",
  "items": [
    {
      "invoice_id": "INV-000101",
      "issued_at": "2026-08-01T09:30:00+09:00",
      "amount": 132000,
      "currency": "JPY",
      "status": "issued"
    }
  ]
}

パラメータ表だけでサンプルを省くと、クエリ文字列の連結、日時の書式、認証ヘッダ名で必ず質問が来ます。タイムゾーンの「+」を%2Bにエンコードすることも、表だけでは伝わりません。応答側も、正常時のJSONを1件貼れば、金額が整数か、日時にタイムゾーンが付くか、ページングがカーソル方式かが一度に伝わります。YAMLやJSONの記法そのものはOpenAPIとSwaggerの違いと仕様書の書き方で扱っています。

認証方式の書き方：APIキー・OAuth 2.0・OpenID Connectの記述差

「認証方式：OAuth 2.0」の一行で終わっている仕様書は、実装者から見て情報がほぼありません。デジタル庁のガイドは「API利用者認証を強く推奨する。少なくともAPIキーによる実装以上の認証レベルを担保すること」としたうえで、APIキーを「コピーされアクセスされる可能性もあるため、強固な対策ではない」と明記し、パラメータにAPIキーを含めないこと、不要となったAPIキーを削除することを求めています。行政手続や個人情報を扱うなど個人認証を正確に行う必要がある際はOpenID Connectの認証も行うこと、極めて守秘性の高い情報の認証が必要な場合はそのうちのHybrid Flowを推奨しています。

仕様書には次の4点を重要度順に書いてください。上の2つが欠けると接続自体ができません。

1. 資格情報をどこに載せるか（Authorizationヘッダか独自ヘッダか。クエリ文字列は不可と明記）
2. 資格情報の取得手順、有効期限、再発行の方法
3. 認証・認可の失敗時に返すステータス（401と403をどの条件で返し分けるか）
4. スコープや権限の一覧と、エンドポイントごとの必要権限

APIキーなら、載せるヘッダ名と発行・失効の手順でほぼ足ります。OAuth 2.0なら、認可エンドポイントとトークンエンドポイントのURL、グラントタイプ、スコープ名、アクセストークンの有効期限とリフレッシュトークンの扱いまで書かないと、利用側はトークン取得のコードを書けません。OpenID Connectはその上にIDトークンの検証方法とdiscoveryエンドポイントのURLが加わります。資格情報をクエリ文字列に置く仕様は、URLがアクセスログ、プロキシ、Refererに残るので採用しないでください。方式そのものの選び方やトークン寿命の決め方はAPI認証の設計（方式選定とトークン寿命）で扱っています。

エラー仕様の書き方：RFC 9457とステータスコードの割り当て

problem+jsonの5項目と独自拡張の記述例

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60

{
  "type": "https://api.example.com/probs/rate-limit",
  "title": "レート制限を超過しました",
  "status": 429,
  "detail": "1分あたり600回の上限を超えました。60秒後に再試行してください。",
  "instance": "/api/v1/invoices",
  "retry_after_seconds": 60
}

エラー形式を自前で発明する必要はありません。RFC 9457「Problem Details for HTTP APIs」がメディアタイプ application/problem+json と、type、status、title、detail、instanceの5つのメンバを定義し、第3.2節で独自メンバの追加も認めています。デジタル庁のガイドが図2-3に載せる残高不足の例では、balanceとaccountsを追加しています。上の例のretry_after_secondsも同じ拡張です。

typeにはエラー種別ごとのURIを入れ、参照先に説明ページを用意します。typeを省略した場合の既定値は about:blank だとRFC 9457の第3.1.1節が定めているので、該当するURIが無いときは省略するか about:blank を明示してください。空文字やnullで埋めると、利用側のエラーハンドリングが分岐できなくなります。デジタル庁のガイドの表2-7は該当URIが無いときの値を「about:brank」と誤記しているので、引き写さないでください。アプリケーション独自のエラーコード体系やリトライ可否の判断まで設計するなら、APIエラーレスポンス設計のコード体系とリトライ判断が続きにあたります。

公的ガイドが参照するRFCの更新状況

3本は、デジタル庁のガイド（2024年9月30日改定が最終版）の参考文献一覧（表5-3）に載る8本のRFCのうち、現行版に置き換わったものです。RFC 7807はIPAのガイドもエラー形式の準拠先に挙げています。新しく書く仕様書は9457を引いてください。メンバ名は変わっていないので、番号の差し替えだけで済みます。

ステータスコードの説明文も、公的資料からではなくRFCから起こしてください。IPAのガイドの表6は429の説明を「サーバ側での処理中にエラーが発生」としており、デジタル庁の表2-2の「クライアントが短時間に多すぎるリクエストを送信した」と食い違います。IPAの表6には500 Internal Server Errorの行そのものが無く、レート制限超過は403の説明に入っているので、誤植というより行構成のずれです。429を定義するのはRFC 6585の第4節で、RFC 9110には含まれていません。同節はRetry-Afterを含めてもよい（MAY）とする一方、429の応答をキャッシュに保存してはならない（MUST NOT）と定めているので、CDNを前に置く構成では仕様書で明言してください。

利用制限の書き方：標準化前のレート制限ヘッダと明記すべき6点

レート制限の残量を伝えるHTTPヘッダは、2026年10月時点でまだ標準化されていません。IETFの「RateLimit header fields for HTTP」（draft-ietf-httpapi-ratelimit-headers）は、2026年5月23日提出の第11版が最新のInternet-Draftで、この版の有効期限は2026年11月24日です。デジタル庁のガイドが表2-3で例示するX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Resetは、標準ではなく慣行です。

標準が無い以上、仕様書で書き切るしかありません。次の6点を埋めてください。

1. 上限の数値（回数と単位時間）
2. 超過時のステータスコード（429）とRetry-Afterを返すかどうか
3. 制限の適用単位（APIキー単位、利用者単位、IP単位）
4. ヘッダ名（X-RateLimit-系か独自名か）
5. Resetの単位（残り秒数かUnix時間か。デジタル庁の例は1372700873というUnix時間）
6. 集計窓の種類（固定窓か移動窓か）

数値は必ず数字で書きます。IPAのガイドは「1分間に5000リクエストまで許可する」と例示し、デジタル庁が引くRESAS APIの記入例は「上限：2000回/日」です。「大量アクセスはご遠慮ください」は仕様ではなくお願いで、利用側は再試行の間隔を設計できません。

版管理と変更履歴の書き方：分冊の判断基準

国税庁の法人番号システムWeb-APIは、解説書を6編に分けています。第一編が利用手続（共通編）、第二編が概要編、第三編から第六編がVer.1.0からVer.4.0までのバージョン別です。第一編の表1によればVer.1.0の提供開始は2015年12月、Ver.4.0は2019年3月で、「Ver.1.0～Ver.3.0は、新しいバージョンの提供開始後も引き続きご利用できます」という記述のもと、10年以上前の版がいまも並行稼働しています。

真似できるのは、変更内容と変更理由を別の列に分けている点です。第五編（Ver.3.0・1.4版・令和4年4月）の改版履歴では、1.4版の変更内容が「情報記録媒体によるデータ提供に関する記載を削除」、変更理由が「全件データの情報記録媒体によるデータ提供のサービス終了」と対になっています。

分冊の損得も同じ資料から読めます。この1.4版の変更は同じ文言で第一編の4.6版にも入っており、1つの変更を複数の編へ波及させる手間が発生しています。一方で第一編は利用規約の改正などで改版が続き、2026年9月の4.10版で13回目の改版（改版履歴の14件目）になりましたが、バージョン別の4編は2021年10月から2022年4月の版のまま止まっています。規約や手続の変更は共通編だけで吸収できているわけです。

判断は単純です。運用中のバージョンが1つなら分冊しない。破壊的変更で旧バージョンを残す運用に入った時点で分ける。ただし版を残しても通信要件は動きます。同サイトはサーバ証明書とセキュリティ設定の変更を告知しており、2026年9月30日のお知らせで実施日を2026年10月31日（土）10時から20時までのメンテナンスと確定させました。旧版の文書を残すことと旧い通信環境での動作を保証することは別だと、仕様書に書き分けてください。IPAのガイドはinfo.versionにセマンティックバージョニングを使い、CHANGELOG.mdへのリンクをinfo.descriptionかexternalDocsから張るよう勧めています。URIパスとヘッダのどちらで版を指定するかは、Google API設計ガイドとAIPの主要規約が参考になります。

API設計書のレビュー観点：提出前に確認する12項目

設計書のレビューが誤字の指摘で終わるのは、観点が決まっていないからです。前章までの内容を、受け取った側の立場で上から順に答えられる形に並べました。

最初の3つが不合格なら、残りを見る前に差し戻してください。接続できない設計書は、その先をいくら直しても実装に入れません。「nullと項目欠落の区別」と「更新タイミング」は結合テストや本番稼働後に初めて表面化する項目なので、レビューで拾わないと手戻りが最も大きくなります。ここで見ているのは文書の書き漏れです。URIの切り方、冪等性、ページング方式といった設計の良し悪しはREST API設計のレビュー基準（URI・冪等性・エラー応答）で別に判定してください。2つを1回の会議で同時にやると、どちらも浅くなります。

正本を1つに決める運用：OpenAPIへ移す判断とCIでの検査

API設計書が実装とずれる原因は、書き方より運用にあります。生成したExcel、実装から出したYAML、手で直したREADMEが並び、どれが正しいのか誰も答えられない状態です。

OpenAPIへ移す判断と、使う版

移すかどうかは、クライアントSDKを配布する、実装前にモックを立てる、CIで破壊的変更を検知する、のいずれかに当てはまるかで決めてください。デジタル庁のガイドもOASからAPIモックを自動生成できるツールの使用を推奨しています。社内の1システム間連携でエンドポイントが数本、読み手が同じチーム内なら、YAMLに移しても二重管理が増えるだけです。IPAも事例の法人番号システムWEB-APIについて「仕様書はWORD形式のPDFで公開され、API標準設計書の形式では提供されていない」と記しています。機械可読化は、再利用される項目定義から始めても構いません。

OpenAPI Specificationの改訂履歴では、最新は2026年9月10日の3.2.1で、3.1系は3.1.2（2025年9月19日）、3.0系は3.0.4（2024年10月24日）が各系統の最新パッチです。ツールチェーンが3.2に対応しているか確かめるまでは、3.1.2で書くのが無難です。実装側に型定義があるなら、ZodのスキーマからOpenAPIを生成する方法のように既存の定義を出力元にすると二重管理を避けられます。

設計先行か実装先行かで決まる正本の置き場所

設計を先に書く設計先行なら正本はYAMLで、スタブやクライアントのコードはYAMLから生成し、手で編集しません。アノテーションや型定義から仕様を出力する実装先行なら、正本はコードでYAMLが生成物です。どちらでも成り立ちますが、両方を手で書く運用だけは成り立ちません。フロントエンドとバックエンドを並行で進める設計先行の組み立ては、スキーマファーストによるOpenAPI起点の並行開発で詳しく扱っています。

プルリクエストでのlintと破壊的変更の検知

正本を決めたら、人のレビューに頼らず機械で止めます。書き漏れはSpectralのlintで、互換性を壊す変更はoasdiffの差分検査で検出できます。

# .spectral.yaml（組み込みのOAS用ルールセットに、社内ルールを足す）
extends: ["spectral:oas"]
rules:
  operation-description: error
  info-contact: off

# ローカルやCIでのlint（版を固定して結果を再現できるようにする）
npx @stoplight/[email protected] lint openapi.yaml

# mainブランチの設計書と比べて破壊的変更があれば失敗させる
git fetch origin main --depth=1
git show origin/main:openapi.yaml > base.yaml
oasdiff breaking base.yaml openapi.yaml --fail-on ERR

info-contactを切っているのはサンプルに窓口が無いためで、本番の設計書ではinfo.contactに問い合わせ窓口を書き、このルールも有効のまま残してください。GitHub Actionsの既定のcheckoutは履歴を1件しか取らないので、比較元のmainを先にfetchしておかないとgit showが失敗します。

OpenAPIサンプルの章で示した修正版を基準にし、limitを必須に変え、Invoiceからcurrencyを消した版をoasdiff v1.34.0（日本時間2026年10月19日リリース）で比べると、次の2件をerrorとして返し、終了コード1で止まりました。同じファイル同士なら「No changes detected」で終了コード0です。

2 changes: 2 error, 0 warning, 0 info
error	[request-parameter-became-required] at changed.yaml
	in API GET /invoices
		the `query` request parameter `limit` became required

error	[response-required-property-removed] at changed.yaml
	in API GET /invoices
		removed the required property `items/items/currency` from the response with the `200` status

どちらも既存の利用側のコードがそのまま壊れる変更で、版管理の章で書いた、旧バージョンを残す運用に入るタイミングにCIの結果で気づけます。レビュー表のうち機械で判定できる項目はSpectralの独自ルールへ移すと、人が見る項目が減ります。最後に、生成したExcelやHTMLの先頭に「このファイルは openapi.yaml から生成。手で編集しない」と1行入れておくと、生成物を手で直す事故の大半を防げます。社外に配るAPI設計書や既存システムとの連携仕様の整理から相談したい場合は、API開発・システム連携の支援で要件の段階から受け付けています。

よくある質問

API仕様書とは何ですか？

APIを利用する側に向けて、接続先・認証方法・送るデータ・返るデータ・エラーの意味を、確定した内容で記述した文書です。デジタル庁のAPIテクニカルガイドブックは、API機能、API利用方法、エラーコード、リクエスト、レスポンス、提供データに関する説明の6項目を挙げ、利用申請や利用規約は別の文書として整理しています。

API仕様書とAPI設計書は何が違いますか？

読み手と、内容が確定しているかどうかが違います。設計書は作る側の内部文書で未確定事項を含み、仕様書は使う側に配る外部文書で確定した振る舞いだけを載せます。IPAのAPI標準設計ガイド・基礎編はOASのYAMLファイルを「API標準設計書」と呼んでおり、両者を兼ねる形です。社外公開があるなら分け、社内で完結するなら1つにまとめてください。

API仕様書のテンプレートやサンプルはそのまま使えますか？

項目の抜け防止には有効ですが、多くのテンプレートは「提供データに関する説明」の枠を持たず、レスポンス項目がnullになり得るかを書く列もありません。本文のMarkdownテンプレートのように、更新タイミングとnull可否の欄を足してから使ってください。

API仕様書に認証方式はどこまで書けばよいですか？

方式名だけでは足りません。資格情報を載せるヘッダ名、取得手順と有効期限、再発行の方法、401と403の返し分け、スコープと権限の一覧まで書いて初めて利用側が実装できます。OAuth 2.0なら認可・トークン両エンドポイントのURL、グラントタイプ、リフレッシュトークンの扱いも必要です。

APIのエラーコードは仕様書にどこまで書くべきですか？

HTTPステータスコードとアプリケーション独自のエラーコードの両方を一覧にします。国税庁の法人番号システムWeb-APIは「HTTPステータスコード、エラーコード及びエラーメッセージ一覧」を別紙として独立させています。形式はRFC 9457に合わせ、429の根拠はRFC 9110ではなくRFC 6585である点に注意してください。

API設計書はExcelとOpenAPI（Swagger）のどちらで作るべきですか？

どちらか一方に決めるのではなく、正本をどちらにするかを決めます。SDK配布、モック生成、CIでの破壊的変更検知のいずれかを狙うならOpenAPIのYAMLを正本にしてExcelは出力物にし、発注側がExcel様式を指定しているならExcelを正本にします。OpenAPIで書く場合、2026年10月時点の最新は3.2.1ですが、ツールの対応を確かめるまでは3.1.2が無難です。

関連記事

• API設計とは？リソース定義からURI・スキーマ・エラー・版管理までの実装手順
• OpenAPIとは？Swaggerとの違いと仕様書(YAML/JSON)の書き方｜3.0・3.1・3.2の差分
• スキーマファーストとは？OpenAPI起点の並行開発と破壊的変更検知を解説
• REST API設計のベストプラクティス｜URI・冪等性・エラー応答のレビュー基準
• APIエラーレスポンス設計とは？コード体系・リトライ判断・漏洩防止の実装手順