API仕様書に記載すべき内容と例

API仕様書は、APIを利用する開発者にとって必要な情報を明確に記載する文書です。以下に、API仕様書に含めるべき項目とその例を紹介します。

---

1. 概要

目的: APIの全体像を簡潔に説明します。

記載内容:

• APIの名前
• 提供する主な機能や目的
• 対象ユーザー（フロントエンド開発者、モバイルアプリ開発者など）
• サポートするクライアント（例: Webブラウザ、モバイルアプリ）

例:

markdownコピーする編集する# API概要
このAPIは、ユーザー情報の管理やデータ取得を提供します。モバイルアプリやWebアプリケーションのバックエンドとして使用されます。

---

2. 基本情報

APIの利用に必要な基本情報を記載します。

記載内容:

• ベースURL
• サポートするプロトコル（HTTP, HTTPS）
• 対応するバージョン
• 認証方式（例: OAuth 2.0, APIキー, JWTトークン）

例:

markdownコピーする編集する## 基本情報
- ベースURL: `https://api.example.com/v1`
- プロトコル: HTTPS
- バージョン: v1
- 認証方式: Bearerトークン (JWT)

---

3. エンドポイント一覧

APIの各エンドポイントを一覧で記載し、利用者が必要なエンドポイントを見つけやすくします。

記載内容:

• HTTPメソッド（GET, POST, PUT, DELETE）
• エンドポイントのURL
• 簡単な説明

例:

markdownコピーする編集する## エンドポイント一覧
| メソッド | エンドポイント          | 説明                     |
|----------|-------------------------|--------------------------|
| GET      | /users                 | ユーザーの一覧を取得する |
| POST     | /users                 | 新しいユーザーを作成する |
| GET      | /users/{id}            | 特定のユーザーを取得する |
| PUT      | /users/{id}            | ユーザー情報を更新する   |
| DELETE   | /users/{id}            | ユーザーを削除する       |

---

4. 各エンドポイントの詳細

各エンドポイントについて、詳細な仕様を記載します。

記載内容:

• エンドポイントのURL
• HTTPメソッド
• 機能概要
• 必要なパラメータ（リクエストボディ、クエリパラメータ、ヘッダー）
• レスポンス形式（成功時・エラー時）
• ステータスコード一覧

例:

markdownコピーする編集する### GET /users
- **説明**: 全てのユーザー情報を取得します。
- **認証**: 必要 (Bearerトークン)

#### クエリパラメータ:
| パラメータ名 | 必須 | 型     | 説明           |
|-------------|------|--------|----------------|
| limit       | 任意 | int    | 取得件数の上限 |
| offset      | 任意 | int    | 取得開始位置   |

#### リクエスト例:

GET /users?limit=10&offset=0
Authorization: Bearer <your_token>

bashコピーする編集する
#### レスポンス例（成功時）:
```json
{
    "users": [
        {
            "id": 1,
            "name": "John Doe",
            "email": "john.doe@example.com"
        },
        {
            "id": 2,
            "name": "Jane Doe",
            "email": "jane.doe@example.com"
        }
    ],
    "total": 100
}

ステータスコード:

ステータスコード	説明
200	正常に処理されました
401	認証に失敗しました
500	サーバー内部エラー

yamlコピーする編集する
---

### 5. データモデル

APIが送受信するデータの形式（スキーマ）を記載します。

#### 記載内容:
- フィールド名
- データ型（string, int, boolean, array, object）
- 必須/任意
- 説明

**例**:
```markdown
### ユーザーデータモデル
| フィールド名 | 型       | 必須 | 説明                     |
|-------------|----------|------|--------------------------|
| id          | int      | 必須 | ユーザーの一意識別子     |
| name        | string   | 必須 | ユーザーの名前           |
| email       | string   | 必須 | ユーザーのメールアドレス |
| isActive    | boolean  | 任意 | ユーザーが有効かどうか   |

---

6. 認証

APIの認証方式を記載します。

例:

markdownコピーする編集する### 認証方式
- **方式**: Bearerトークン (JWT)
- **ヘッダー例**:

Authorization: Bearer <your_token>

markdownコピーする編集する
- **トークン取得方法**:
  - POST `/auth/login`
  - **リクエストボディ**:
    ```json
    {
        "username": "example",
        "password": "password123"
    }
    ```

---

7. エラーハンドリング

APIが返すエラーとその意味を記載します。

例:

markdownコピーする編集する### エラー一覧
| ステータスコード | メッセージ              | 説明                            |
|------------------|-------------------------|---------------------------------|
| 400              | Bad Request            | 無効なリクエスト                |
| 401              | Unauthorized           | 認証が必要                      |
| 404              | Not Found              | リソースが見つかりません        |
| 500              | Internal Server Error  | サーバー内部エラー              |

---

8. サンプルコード

APIの使用例を記載します。

例（JavaScript）:

javascriptコピーする編集するfetch('https://api.example.com/v1/users', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer your_token'
    }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));

---

9. バージョン管理と変更履歴

APIのバージョンごとの変更点を記載します。

例:

markdownコピーする編集する### バージョン履歴
- **v1.0**:
  - 初期リリース。
- **v1.1**:
  - ユーザーのステータス（isActive）を追加。

---

まとめ

API仕様書に記載するべき内容は以下の通りです：

1. 概要
2. 基本情報
3. エンドポイント一覧
4. 各エンドポイントの詳細
5. データモデル
6. 認証
7. エラーハンドリング
8. サンプルコード
9. バージョン管理と変更履歴

これらの情報を明確に記載することで、開発者がAPIをスムーズに利用できるようになります。