API設計書の書き方｜Markdown・OpenAPIテンプレートと記入例

API設計書とは、APIを使う人と作る人が「何を送ると、何が返るか」を同じ理解で持つための文書です。 書く項目は大きく「全体で共通のルール（認証・エラー形式・ページング・バージョニング・制限）」と「エンドポイントごとの入出力」の2層に分かれます。この2層を表と例で埋めていけば、読み手が迷わない設計書になります。

この記事では、書く項目の一覧表、そのままコピーできるMarkdownテンプレート、そして同じ内容をOpenAPI 3.1で書いたYAMLを、架空のタスク管理APIの記入例で対にして載せます。さらにそのYAMLを Redocly CLI 2.57.0 と Spectral 6.17.0 でlintし、Prism 5.14.2 でモックサーバーを起動してcurlした実際の出力まで掲載しています（Node.js 22.22 で確認）。

API設計書に書く項目の早見表

迷ったら「全体ルール → エンドポイント一覧 → 各エンドポイントの入出力 → ステータスコード」の順に埋めると抜けが出にくいです。

API設計書・API仕様書・OpenAPIの関係

呼び方は組織で揺れますが、API設計書は「なぜその形にしたか」と全体ルールを開発チームで共有する文書、API仕様書（リファレンス）は使う人向けの入出力の正確な定義、OpenAPI定義は人とツールの両方が読むYAML/JSONと分けると整理できます。

おすすめは「判断の理由や運用ルールはMarkdown、入出力の正確な定義はOpenAPI」と役割を分けることです。入出力を両方に手書きすると、片方だけ更新されてずれやすくなります。

Markdown版テンプレート（記入例つき）

そのままコピーして、{ } の部分や記入例を書き換えて使えます。中身はすべてタスク管理APIの記入例です。

# タスク管理 API 設計書

| 項目 | 内容 |
|---|---|
| 版 | 1.0.0（2026-10-01） |
| 担当 | {API担当チーム名} |
| OpenAPI定義 | `task-api.yaml`（入出力の定義はこちらを正とする） |

## 1. 概要
- 目的：タスクの登録・参照・更新・削除を外部の画面やバッチから行えるようにする
- 利用者：自社Web画面、スマートフォンアプリ
- ベースURL：`https://api.example.com/v1`

## 2. 共通ルール
### 2.1 認証
- `Authorization: Bearer <アクセストークン>`（JWT、有効期限1時間）
- トークンなし・期限切れは 401

### 2.2 共通ヘッダー
| ヘッダー | 方向 | 必須 | 内容 |
|---|---|---|---|
| Content-Type | 送信 | 本文があるとき | `application/json`（PATCHは `application/merge-patch+json`） |
| Idempotency-Key | 送信 | 任意 | 登録APIの二重送信防止（UUID） |
| RateLimit-Remaining | 受信 | - | 残りリクエスト数 |

### 2.3 データ形式
- 文字コード UTF-8、項目名は lowerCamelCase
- 日付 `YYYY-MM-DD`、日時は UTC の ISO 8601（例 `2026-10-01T09:00:00Z`）
- 値がないときは項目を `null` にする（項目自体は省略しない）

### 2.4 エラー形式（RFC 9457）
```json
{"type":"https://api.example.com/problems/validation-error","title":"Validation Error","status":422,"errors":[{"field":"title","message":"1〜100 文字で入力してください"}]}
```

### 2.5 ページング
- カーソル方式。`limit`（1〜100、既定20）と `cursor` を送る
- レスポンスの `nextCursor` が `null` なら最終ページ

### 2.6 バージョニング
- URLに `/v1`。項目の追加は同じ版で行い、削除・型変更は `/v2` を用意する
- 旧版は告知から6か月提供する

### 2.7 制限
- 1ユーザー1分60回。超えたら 429 と `Retry-After`（秒）
- 本文は1MBまで

## 3. エンドポイント一覧
| No | メソッド | パス | 機能 | 主なステータス |
|---|---|---|---|---|
| 1 | GET | /tasks | 一覧取得 | 200, 400, 401, 429 |
| 2 | POST | /tasks | 登録 | 201, 400, 401, 422 |
| 3 | GET | /tasks/{taskId} | 1件取得 | 200, 401, 404 |
| 4 | PATCH | /tasks/{taskId} | 部分更新 | 200, 401, 404, 422 |
| 5 | DELETE | /tasks/{taskId} | 削除 | 204, 401, 404 |

## 4. エンドポイント詳細
### 4.2 POST /tasks（登録）
**リクエスト本文**
| 項目 | 型 | 必須 | 制約 | 説明 |
|---|---|---|---|---|
| title | string | ○ | 1〜100文字 | タスク名 |
| dueDate | string | null | - | `YYYY-MM-DD` | 期限 |

**レスポンス**
| ステータス | 条件 | 本文 |
|---|---|---|
| 201 | 登録成功 | Task。`Location` ヘッダーに作成先URL |
| 400 | JSONとして読めない | Problem |
| 401 | 認証エラー | Problem |
| 422 | 入力チェックエラー | Problem（`errors` に項目別の理由） |

## 5. 変更履歴
| 日付 | 版 | 内容 |
|---|---|---|
| 2026-10-01 | 1.0.0 | 初版 |

Markdownの表に入れるのは「要約と判断の理由」までにし、項目の型や制約の細部は次のOpenAPI定義に寄せると、更新漏れが減ります。

同じ内容をOpenAPI 3.1で書いた記入例（task-api.yaml）

上のMarkdownと同じタスク管理APIを、OpenAPI 3.1.1で書いたものです。このファイルをそのまま保存すると、後半のlintとモックサーバーの手順がそのまま再現できます。

openapi: 3.1.1
info:
  title: タスク管理 API
  version: 1.0.0
  description: 架空のタスク管理サービスの API 設計書（記入例）
servers:
  - url: https://api.example.com/v1
security:
  - bearerAuth: []
tags:
  - name: tasks
    description: タスクの登録・参照・更新・削除
paths:
  /tasks:
    get:
      tags: [tasks]
      operationId: listTasks
      summary: タスク一覧を取得する
      description: 作成日時の新しい順に返す。カーソル方式でページングする。
      parameters:
        - { name: status, in: query, schema: { $ref: '#/components/schemas/TaskStatus' } }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
        - { name: cursor, in: query, description: 前のレスポンスの nextCursor, schema: { type: string } }
      responses:
        '200':
          description: 取得成功
          headers:
            RateLimit-Remaining: { description: 残りリクエスト数, schema: { type: integer } }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TaskList' }
              example:
                items: [{ id: tsk_01J9Z3K8QW, title: 備品の発注, status: todo, dueDate: '2026-10-10', createdAt: '2026-10-01T09:00:00Z', updatedAt: '2026-10-01T09:00:00Z' }]
                nextCursor: eyJpZCI6InRza18wMUo5WjNLOFFXIn0
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
    post:
      tags: [tasks]
      operationId: createTask
      summary: タスクを登録する
      description: Idempotency-Key が同じ再送は 1 回目と同じ結果を返す。
      parameters:
        - { name: Idempotency-Key, in: header, schema: { type: string, format: uuid } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TaskCreate' }
            example: { title: 備品の発注, dueDate: '2026-10-10' }
      responses:
        '201':
          description: 登録成功
          headers:
            Location: { description: 作成したタスクの URL, schema: { type: string }, example: /v1/tasks/tsk_01J9Z3K8QW }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Task' }
              example: { id: tsk_01J9Z3K8QW, title: 備品の発注, status: todo, dueDate: '2026-10-10', createdAt: '2026-10-01T09:00:00Z', updatedAt: '2026-10-01T09:00:00Z' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '422': { $ref: '#/components/responses/ValidationError' }
  /tasks/{taskId}:
    parameters:
      - { name: taskId, in: path, required: true, schema: { type: string, pattern: '^tsk_[0-9A-Z]{10}$' } }
    get:
      tags: [tasks]
      operationId: getTask
      summary: タスクを 1 件取得する
      description: 他のユーザーのタスクは 404 を返す（存在を知らせない）。
      responses:
        '200':
          description: 取得成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Task' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      tags: [tasks]
      operationId: updateTask
      summary: タスクを部分更新する
      description: 送った項目だけを更新する（JSON Merge Patch）。
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema: { $ref: '#/components/schemas/TaskUpdate' }
            example: { status: done }
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Task' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationError' }
    delete:
      tags: [tasks]
      operationId: deleteTask
      summary: タスクを削除する
      description: 削除済みの ID を再度削除した場合も 404 を返す。
      responses:
        '204': { description: 削除成功（本文なし） }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
  schemas:
    TaskStatus: { type: string, enum: [todo, doing, done] }
    Title: { type: string, minLength: 1, maxLength: 100 }
    DueDate: { type: [string, 'null'], format: date }
    Task:
      type: object
      required: [id, title, status, createdAt, updatedAt]
      properties:
        id: { type: string, readOnly: true }
        title: { $ref: '#/components/schemas/Title' }
        status: { $ref: '#/components/schemas/TaskStatus' }
        dueDate: { $ref: '#/components/schemas/DueDate' }
        createdAt: { type: string, format: date-time, readOnly: true }
        updatedAt: { type: string, format: date-time, readOnly: true }
    TaskCreate:
      type: object
      required: [title]
      additionalProperties: false
      properties:
        title: { $ref: '#/components/schemas/Title' }
        dueDate: { $ref: '#/components/schemas/DueDate' }
    TaskUpdate:
      type: object
      minProperties: 1
      additionalProperties: false
      properties:
        title: { $ref: '#/components/schemas/Title' }
        status: { $ref: '#/components/schemas/TaskStatus' }
        dueDate: { $ref: '#/components/schemas/DueDate' }
    TaskList:
      type: object
      required: [items]
      properties:
        items: { type: array, items: { $ref: '#/components/schemas/Task' } }
        nextCursor: { type: [string, 'null'], description: 次ページがなければ null }
    Problem:
      type: object
      description: RFC 9457 Problem Details
      required: [type, title, status]
      properties:
        type: { type: string, format: uri-reference }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
        errors:
          type: array
          items: { type: object, properties: { field: { type: string }, message: { type: string } } }
  responses:
    BadRequest:
      description: リクエストの形式が不正
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          example: { type: 'https://api.example.com/problems/bad-request', title: Bad Request, status: 400, detail: limit は 1〜100 の整数で指定してください }
    Unauthorized:
      description: 認証情報がない、または無効
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          example: { type: 'https://api.example.com/problems/unauthorized', title: Unauthorized, status: 401 }
    NotFound:
      description: 指定したタスクが存在しない
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          example: { type: 'https://api.example.com/problems/not-found', title: Not Found, status: 404 }
    ValidationError:
      description: 入力値がルールに合わない
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          example: { type: 'https://api.example.com/problems/validation-error', title: Validation Error, status: 422, errors: [{ field: title, message: 1〜100 文字で入力してください }] }
    TooManyRequests:
      description: リクエスト数の上限を超えた
      headers:
        Retry-After: { description: 再試行までの秒数, schema: { type: integer } }
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
          example: { type: 'https://api.example.com/problems/rate-limited', title: Too Many Requests, status: 429 }

Markdownの項目とOpenAPIの対応

OpenAPIの文法そのもの（$ref の分割、チームでの運用）は「OpenAPIの書き方｜YAMLのテンプレートとチームで使う運用」の記事で詳しく扱っているので、ここでは設計書としての書き方に絞ります。

OpenAPIはどの版で書くか

2026年10月時点で、公式サイト（spec.openapis.org）の最新版は OpenAPI 3.2.1（2026年9月10日公開） です。3.2系は2025年9月公開の3.2.0から始まっています。

この記事のYAMLは3.1.1で書いています。参考までに先頭行を openapi: 3.2.0 に変えたファイルでも、Redocly CLI 2.57.0 と Spectral 6.17.0 のlintはエラー0件、Prism 5.14.2 の起動とGETへの200応答まで確認できました（3.2で追加された機能自体は使っていない範囲での確認です）。版を決めるときは、コード生成・ドキュメント表示・モックなど、使うツール全部の対応状況を先に確認すると安心です。

lintで設計書の抜けを見つける（Redocly CLI・Spectral）

lint（リント）とは、定義ファイルの書き方の誤りやルール違反を機械的に見つける検査です。レビューの前にかけておくと、人は設計の中身の確認に集中できます。

# Node.js 22.22 で確認
npm init -y
npm i -D @redocly/cli @stoplight/spectral-cli @stoplight/prism-cli

npx redocly lint task-api.yaml

echo 'extends: ["spectral:oas"]' > .spectral.yaml
npx spectral lint task-api.yaml

実行結果（正しいファイル）

Redocly CLI 2.57.0 の出力（抜粋）です。

validating task-api.yaml...
[1] task-api.yaml:2:1 at #/info
Warning was generated by the info-license rule.
[2] task-api.yaml:7:10 at #/servers/0/url
Server `url` should not point to example.com or localhost.
Warning was generated by the no-server-example.com rule.
Woohoo! Your API description is valid. 🎉
You have 2 warnings.

Spectral 6.17.0 の出力です。

 2:6  warning  info-contact  Info object must have "contact" object.  info

✖ 1 problem (0 errors, 1 warning, 0 infos, 0 hints)

警告はどちらも「info に license や contact を書く」「サーバーURLが example.com」という内容で、記入例ならではのものです。公開するAPIなら info.contact（問い合わせ先）と info.license を書いておくと警告が消えます。 各エンドポイントの description を省いた版では、Spectralが operation-description の警告を5件出しました。説明文の書き漏れもツールで見つけられます。

間違いを2つ入れたときの結果

404 の参照先を NotFoud と打ち間違え、パスパラメーター taskId の required: true を消したファイルで試しました。

# Redocly CLI 2.57.0
[1] bad.yaml:125:11 at #/paths/~1tasks~1{taskId}/get/responses/404
Can't resolve $ref
Error was generated by the no-unresolved-refs rule.
❌ Validation failed with 1 error and 1 warning.

# Spectral 6.17.0
 125:17  error  invalid-ref   '#/components/responses/NotFoud' does not exist
 176:12  error  oas3-schema   "TaskId" property must have required property "required".
 176:12  error  path-params   Path parameter "taskId" must have "required" property that is set to "true".
✖ 9 problems (4 errors, 5 warnings, 0 infos, 0 hints)

※この確認はパラメーターを components.parameters に分けた版で行ったため、行番号は上のYAMLと一致しません。

この組み合わせでは、参照切れは両方が検出し、パスパラメーターの required 漏れはSpectralだけが検出しました。 既定ルールの範囲が違うので、CIでは片方に寄せる場合も「どのルールが有効か」を一度確認しておくと安心です。

Prismでモックサーバーを起動して確認する

Prism（プリズム）は、OpenAPI定義だけで「それらしい応答を返すサーバー」を立てるツールです。実装がなくても、画面側の開発やレビューで実際にリクエストを送れます。定義の制約（maximum や minLength など）でリクエストも検査してくれます。

npx prism mock -p 4010 task-api.yaml

別のターミナルからcurlで確認した結果です（Prism 5.14.2。検証ではポート番号だけ変えて実行し、ヘッダーは主要なものだけ抜粋しています）。

# Prism は servers の /v1 を付けずに /tasks で受け付ける
B=http://127.0.0.1:4010
curl -i $B/tasks -H 'Authorization: Bearer dummy'

各ケースの結果をまとめると次のとおりです。

入力エラーのときは、どの定義に違反したかが sl-violations ヘッダーに入ります。

$ curl -i -X POST $B/tasks -H 'Authorization: Bearer dummy' -H 'Content-Type: application/json' -d '{"title":""}'
HTTP/1.1 422 Unprocessable Entity
sl-violations: [{"location":["request","body","title"],"severity":"Error","code":"minLength","message":"Request body property title must NOT have fewer than 1 characters"}]
Content-type: application/problem+json
{"type":"https://api.example.com/problems/validation-error","title":"Validation Error","status":422,"errors":[{"field":"title","message":"1〜100 文字で入力してください"}]}

モックで「この入力なら何が返るか」を設計の段階で確かめられるので、エラー時の応答の書き漏れにも早く気づけます。

命名・ステータスコード・エラーの設計判断表

設計の考え方そのものは「REST APIの設計｜URL・ステータスコード・エラー形式の決め方」「APIエラーレスポンス設計｜RFC 9457準拠のJSON例と実装コード」の記事で詳しく扱っています。ここでは設計書に書き残すべき判断だけを表にします。

「なぜそう決めたか」まで1行書いておくと、後から読む人が同じ判断を繰り返さずに済みます。

API設計書のレビュー用チェックリスト

よくある質問

Q. API設計書はExcelとMarkdownとOpenAPIのどれで書けばよいですか？ A. 入出力の定義はOpenAPIで書くと、lint・モック・ドキュメント生成までツールでつながります。判断の理由や運用ルールはMarkdownが書きやすく、Gitで差分も見られます。Excelで受け渡す必要があるときも、元はOpenAPIにして必要な表だけ書き出すと、ずれが起きにくくなります。

Q. OpenAPIは3.0・3.1・3.2のどれで書くべきですか？ A. 新しく書くなら3.1が標準的な選択です。最新は3.2.1（2026年9月公開）ですが、使うツールすべてが対応しているかを先に確認しましょう。この記事のYAMLは3.1.1で書き、Redocly CLI・Spectral・Prismで動作を確認しています。

Q. API設計書には内部の処理（DBの更新内容など）も書きますか？ A. API設計書には「外から見える約束」（入力・出力・エラー・制限）を書き、内部の処理は詳細設計書に分けると読み手がはっきりします。書き分けの考え方は「詳細設計書の書き方｜基本設計との違いと記入例」の記事も参考になります。

まとめ

• API設計書は「全体ルール」と「エンドポイントごとの入出力」の2層で書く
• 全体ルールは認証・共通ヘッダー・データ形式・エラー形式・ページング・バージョニング・制限の7つ
• 判断の理由はMarkdown、入出力の定義はOpenAPIを正にすると、ずれが起きにくい
• 制約は文章でなく数値（maxLength・maximum・pattern・enum）で書くと、ツールが検査できる
• Redocly CLI・Spectralのlintで参照切れや必須漏れを、レビュー前に機械で見つけられる
• Prismのモックで、設計段階からエラー応答まで実際に確かめられる
• レビューはチェックリストで、エラー時・0件・権限の書き漏れを確認する

株式会社RJCでは、API設計書の書き方を仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。