# 第14章　設計フェーズ別のAPIdog活用

> **ナビゲーション**
>
> * 前の章: [第13章　APIdogとグランドデザインの接点](/ja/solutions/part6-apidog/ch13-apidog-overview.md)
> * 次の章: [第15章　このグランドデザインが目指すもの](/ja/solutions/part7-future/ch15-vision.md)

***

![APIdogはグランドデザインを「静的な設計書」から「生きているシステム」へと進化させる](/files/O7m4ppe68hNSYNpqHcn0)

## この章で学ぶこと

前章でAPIdogの基本概念と「設計の錨」としての役割を学びました。この章では、**グランドデザインの実装を3つのフェーズに分け**、各フェーズでAPIdogをどう活用するかを具体的に説明します。

```
Phase 1: スキーマ設計
   ↓
Phase 2: モックサーバーとゲートウェイ設計
   ↓
Phase 3: 継続的ベンチマーク
```

![実装プロセスは「定義・モック・測定」の3フェーズで科学的かつ反復的に進行する](/files/Qzs6UYCJZU5z5Qt5hObn)

***

## 14.1 Phase 1：スキーマ設計

### このフェーズの目標

「チーム全員が合意できる共通スキーマ」を定義し、APIdogに登録します。ここで合意したスキーマが、以降のすべての作業の基盤になります。

***

### 共通スキーマの定義手順

#### ステップ1：プロジェクトの作成

APIdogにログイン後、「新規プロジェクト」を作成します。

推奨設定：

```
プロジェクト名: 言語APIワールド ゲートウェイ
バージョン: 0.1.0
サーバーURL: http://localhost:8080 （開発用）
```

#### ステップ2：Componentsに共通型を定義する

APIdogのメニューから「コンポーネント」→「スキーマ」を選び、以下の共通型を順番に登録します。

**ContentObject（コンテンツオブジェクト）**

言語サービスに渡すコンテンツの共通表現です。

```yaml
ContentObject:
  type: object
  required:
    - content
    - contentType
  properties:
    content:
      type: string
      description: 処理するテキストまたはファイルのBase64エンコード
      example: "Hello, world!"
    contentType:
      type: string
      enum: [text/plain, text/html, application/json]
      description: コンテンツのMIMEタイプ
    metadata:
      type: object
      description: コンテンツに付随する任意のメタデータ
      additionalProperties: true
```

**LanguagePair（言語ペア）**

ソース言語とターゲット言語の組み合わせを表します。

```yaml
LanguagePair:
  type: object
  required:
    - targetLanguage
  properties:
    sourceLanguage:
      type: string
      pattern: '^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$'
      description: "ソース言語（BCP-47形式）。省略時は自動検出"
      example: "ja"
    targetLanguage:
      type: string
      pattern: '^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$'
      description: "ターゲット言語（BCP-47形式）"
      example: "en-US"
```

> **BCP-47とは** BCP-47は言語タグの国際標準規格です。`ja`（日本語）、`en-US`（アメリカ英語）、`zh-Hant`（繁体字中国語）のように表記します。詳しくは付録Aの用語集を参照してください。

**QualityTier（品質ティア）**

```yaml
QualityTier:
  type: string
  enum:
    - speed      # 高速・低コスト。MT出力そのまま
    - balanced   # バランス型（デフォルト）
    - quality    # 高品質。ポストエディット含む可能性あり
  default: balanced
```

**StandardError（標準エラーレスポンス）**

すべてのエラーレスポンスをこの形式に統一します。

```yaml
StandardError:
  type: object
  required:
    - code
    - message
    - timestamp
  properties:
    code:
      type: string
      description: "エラーコード（例: VENDOR_UNAVAILABLE, QUOTA_EXCEEDED）"
    message:
      type: string
      description: 人間が読めるエラーメッセージ（日本語可）
    timestamp:
      type: string
      format: date-time
    vendorId:
      type: string
      description: エラーが発生したベンダーID（特定できる場合）
    retryAfter:
      type: integer
      description: "リトライまでの待機秒数（レート制限時）"
```

#### ステップ3：エンドポイントを定義する

Componentsに型を定義したら、エンドポイントを定義します。`$ref` で共通型を参照するため、定義が一箇所に集約されます。

```
エンドポイント例:
  POST /v1/translate     ← テキスト翻訳
  POST /v1/detect        ← 言語自動検出
  POST /v1/stt           ← 音声→テキスト（STT）
  POST /v1/tts           ← テキスト→音声（TTS）
  GET  /v1/vendors       ← 利用可能ベンダー一覧
  GET  /v1/health        ← ヘルスチェック
```

![【Phase 1】プロジェクト作成→共通型（Components）登録→エンドポイント定義の3ステップ](/files/7lxrl57kcrAijR58RRPa)

***

### Componentsを使った型の再利用

APIdogでの `$ref` による参照のメリットを図示します：

```mermaid
flowchart BT
    subgraph Components["📦 Components（共通型定義）"]
        A["ContentObject"]
        B["QualityTier"]
        C["LanguagePair"]
        D["StandardError"]
    end
    E["POST /translate"]
    F["POST /stt"]

    E -->|"$ref で参照"| A
    E -->|"$ref で参照"| B
    F -->|"$ref で参照"| C
    F -->|"$ref で参照"| D
```

`QualityTier` に新しい値（例: `expert_in_the_loop`）を追加したい場合、Components の定義を1か所変更するだけで、参照しているすべてのエンドポイントに自動反映されます。

***

### スキーマ変更の影響範囲を可視化する

APIdogでは「どのエンドポイントがこのスキーマを参照しているか」をUI上で追跡できます。

実践的なワークフロー：

1. `QualityTier` を変更しようとする
2. APIdogの「参照箇所を表示」機能で影響を受けるエンドポイントを確認
3. テストケースに `quality_tier: "expert_in_the_loop"` が追加されていないか確認
4. 影響エンドポイントのテストを実行して、変更が問題ないか検証
5. 問題がなければ変更を確定し、チームに通知

この流れにより、「スキーマを変更したら別の箇所が壊れた」という事態を防ぎます。

![【Phase 1】Components $refにより仕様変更の影響範囲を可視化し「変更→影響確認→テスト→確定」のサイクルで安全に制御する](/files/Ll2m9dLMrA0U9GJL4R4J)

***

## 14.2 Phase 2：モックサーバーとゲートウェイ設計

### このフェーズの目標

スキーマを「動くもの」にします。APIdogのモックサーバーを起動し、実装がなくても APIの動作を確認できる環境を作ります。同時に、ゲートウェイAPIのエンドポイントをAPIdogで詳細設計します。

***

### APIdogのモックサーバーを起動する

#### モックサーバーとは

> **モックサーバー（Mock Server）とは** 「本物のサーバーのふりをするサーバー」です。 たとえば、翻訳ゲートウェイの実装がまだ完了していなくても、「このエンドポイントにリクエストを送ると、こういうレスポンスが返ってくる」という動作を模倣します。 フロントエンドの開発者は「バックエンドができるまで待つ」必要がなくなります。

#### モックサーバーの起動手順

APIdogでのモックサーバー起動は非常に簡単です：

1. プロジェクトの「モック」タブを開く
2. 「モックサーバーを起動」をクリック
3. ローカルURLが発行される（例: `http://127.0.0.1:4010`）
4. このURLに向けてリクエストを送ると、スキーマに基づいたレスポンスが返る

#### モックレスポンスのカスタマイズ

APIdogでは、モックレスポンスに「期待するサンプルデータ」を設定できます：

```json
// POST /v1/translate のモックレスポンス例
{
  "translatedText": "こんにちは、世界！",
  "sourceLanguage": "en",
  "targetLanguage": "ja",
  "vendor": "mock-vendor",
  "qualityTier": "balanced",
  "usage": {
    "characterCount": 13,
    "costEstimateUSD": 0.00026
  },
  "latencyMs": 342
}
```

このサンプルデータを設定しておくと、モックサーバーは毎回このデータを返します。複数のシナリオ（正常系・エラー系）を登録しておくことも可能です。

![【Phase 2】モックサーバーによりフロントエンドはバックエンドの実装を待たずに並行開発を開始できる](/files/toAnvDtnHKS7w5beVT5o)

***

### ゲートウェイAPIのエンドポイントをAPIdogで設計・ドキュメント化

ゲートウェイAPIの各エンドポイントを、APIdogで詳細設計します。

#### POST /v1/translate の詳細設計例

| 項目       | 内容                                  |
| -------- | ----------------------------------- |
| パス       | `POST /v1/translate`                |
| 説明       | テキスト翻訳。ゲートウェイが最適ベンダーを選択して翻訳を実行する    |
| 認証       | Bearer Token（JWT）または APIキー          |
| リクエストボディ | `TranslationRequest` （Components参照） |
| 成功レスポンス  | 200 `TranslationResponse`           |
| エラーレスポンス | 400 / 429 / 500 `StandardError`     |

```yaml
# エンドポイントの詳細スキーマ
TranslationRequest:
  type: object
  required:
    - content
    - targetLanguage
  properties:
    content:
      $ref: '#/components/schemas/ContentObject'
    targetLanguage:
      type: string
      description: "ターゲット言語（BCP-47）"
    sourceLanguage:
      type: string
      description: "省略時は自動検出"
    qualityTier:
      $ref: '#/components/schemas/QualityTier'
    vendorPreference:
      type: array
      items:
        type: string
      description: "優先するベンダーのリスト（例: [\"deepl\", \"google\"]）"
    glossaryId:
      type: string
      description: "使用する用語集のID（事前登録済みのもの）"

TranslationResponse:
  type: object
  properties:
    translatedText:
      type: string
    sourceLanguage:
      type: string
      description: "検出または指定されたソース言語"
    targetLanguage:
      type: string
    vendor:
      type: string
      description: "実際に使用したベンダーID"
    qualityTier:
      $ref: '#/components/schemas/QualityTier'
    usage:
      type: object
      properties:
        characterCount:
          type: integer
        costEstimateUSD:
          type: number
    latencyMs:
      type: integer
      description: "処理時間（ミリ秒）"
```

***

### チームメンバーそれぞれの活用方法

APIdogは役割の異なるメンバーが、それぞれ異なる使い方をします：

#### フロントエンド開発者の活用

```
やること:
  1. APIdogのURLからAPIドキュメントを参照
  2. モックサーバーのURLをフロントエンドのAPIクライアントに設定
  3. バックエンドの実装を待たずにUI開発を進める
  4. レスポンスの形式を確認しながら、表示ロジックを実装

メリット:
  → バックエンド完成を待たなくてよい
  → 「仕様書を読む」のではなく「実際にAPIを叩いて確認」できる
```

#### バックエンド開発者の活用

```
やること:
  1. APIdogのスキーマをもとに実装（スキーマが仕様書になる）
  2. 実装完了後、APIdogのテスト機能で動作確認
  3. スキーマを変更する場合はAPIdogで先に変更し、チームに通知

メリット:
  → 「何を実装すればよいか」が明確
  → 実装とドキュメントの乖離が起きない
```

#### 非エンジニア（PL・調達担当者等）の活用

```
やること:
  1. APIdogが生成したドキュメントをブラウザで参照
  2. 「このAPIは何ができるか」を理解する
  3. ベンダーへの発注要件として「このスキーマに準拠すること」と指定

メリット:
  → コードを読まなくても仕様を理解できる
  → ベンダーとの要件定義の共通言語になる
```

#### ベンダー・外部パートナーの活用

```
やること:
  1. 共有URLからAPIドキュメントを参照
  2. モックサーバーで動作確認・テスト
  3. 実装サンプルコード（APIdogが自動生成）を参考にする

メリット:
  → 「どんなAPIに接続すればよいか」が即座に分かる
  → サンプルコードが自動生成されるため実装コストが低い
```

![【Phase 2】単一のゲートウェイ定義をフロントエンド・バックエンド・非エンジニア・ベンダーの全ステークホルダーが共通言語として活用する](/files/vD3qznH3zHiwmSWH74d7)

***

## 14.3 Phase 3：継続的ベンチマーク

### このフェーズの目標

本番環境に向けて、**複数ベンダーを同一条件で定期的に比較**します。「今日はどのベンダーが最もコスト効率よく高品質な翻訳を提供しているか」を継続的に測定します。

***

### APIdogのテストスイートを使った自動テスト

#### テストスイートとは

APIdogでは、複数のAPIリクエストをまとめて実行し、レスポンスを自動検証する「テストスイート」を作成できます。

テストスイートの基本構成：

```
テストスイート: 「翻訳ベンダー品質ベンチマーク」
  ├── テストケース 1: DeepL翻訳（日→英）
  ├── テストケース 2: Google翻訳（日→英）
  ├── テストケース 3: AWS Translate（日→英）
  ├── テストケース 4: Azure Translator（日→英）
  └── テストケース 5: 結果集計・比較
```

***

### 複数ベンダーへの同一リクエスト比較手順

#### ステップ1：テスト用テキストセットの準備

比較に使うテキストを用意します。実際の業務に近いジャンルを混ぜるのがポイントです。

```json
// テスト用テキストセット（例）
{
  "testCases": [
    {
      "id": "general-001",
      "domain": "一般",
      "text": "本製品のご使用にあたっては、以下の注意事項をお守りください。"
    },
    {
      "id": "legal-001",
      "domain": "法律",
      "text": "本契約は、当事者間の合意に基づき締結されるものとし、準拠法は日本法とします。"
    },
    {
      "id": "medical-001",
      "domain": "医療",
      "text": "患者の同意を得た上で、治療計画の詳細を説明する必要があります。"
    },
    {
      "id": "tech-001",
      "domain": "技術",
      "text": "APIのレイテンシを最小化するため、コネクションプールを適切に設定してください。"
    }
  ]
}
```

#### ステップ2：APIdogでテストケースを作成

各ベンダーへのリクエストをAPIdogのテストケースとして登録します。

テストケースの設定例（DeepL）：

```
名前: DeepL 日→英 翻訳テスト
メソッド: POST
URL: https://api-free.deepl.com/v2/translate
ヘッダー:
  Authorization: DeepL-Auth-Key {{DEEPL_API_KEY}}
  Content-Type: application/json
ボディ:
  {
    "text": ["{{testText}}"],
    "target_lang": "EN-US"
  }

アサーション（検証ルール）:
  - ステータスコードが 200 であること
  - レスポンスに "translations" フィールドが存在すること
  - レスポンスタイムが 3000ms 以下であること
```

> **アサーション（Assertion）とは** 「テストの合格条件」です。「ステータスコードが200であること」「レスポンスに特定のフィールドがあること」などを設定します。条件を満たさなければテスト失敗（FAIL）となります。

#### ステップ3：変数を使った共通化

`{{testText}}` のように変数を使うと、テキストを変えるだけで全ベンダーのテストを一括更新できます。

APIdogの環境変数設定：

```json
// 開発環境
{
  "DEEPL_API_KEY": "xxxx-xxxx-xxxx",
  "GOOGLE_API_KEY": "AIza-xxxx",
  "AWS_ACCESS_KEY": "AKIA-xxxx",
  "AZURE_KEY": "xxxx",
  "testText": "本製品のご使用にあたっては、以下の注意事項をお守りください。"
}
```

![【Phase 3】テストスイートと変数({{testText}})を用いて複数ベンダーへの同一条件比較を自動化する](/files/rCnJyAbFhAJ9bcI9HMwY)

#### ステップ4：テストスイートを実行する

「実行」ボタンを押すと、設定したすべてのテストケースが順番に（または並行して）実行されます。

***

### テストレポートの読み方と意思決定への活用

テスト完了後、APIdogは以下のレポートを生成します：

#### レイテンシ比較表（レポート例）

| ベンダー   | テキスト種別 | レイテンシ(ms) | ステータス |
| ------ | ------ | --------- | ----- |
| DeepL  | 一般文    | 287       | PASS  |
| Google | 一般文    | 412       | PASS  |
| AWS    | 一般文    | 651       | PASS  |
| Azure  | 一般文    | 389       | PASS  |
| DeepL  | 法律文    | 302       | PASS  |
| Google | 法律文    | 445       | PASS  |
| AWS    | 法律文    | 712       | PASS  |
| Azure  | 法律文    | 401       | PASS  |

#### コスト比較表（100万文字あたり推定）

| ベンダー   | 料金（USD/100万文字） | 今回使用文字数 | 推定コスト（USD） |
| ------ | -------------- | ------- | ---------- |
| DeepL  | $25.00         | 1,240文字 | $0.031     |
| Google | $20.00         | 1,240文字 | $0.025     |
| AWS    | $15.00         | 1,240文字 | $0.019     |
| Azure  | $10.00         | 1,240文字 | $0.012     |

![【Phase 3 結果①】ベンチマーク結果を定量評価しレイテンシとコストのトレードオフから最適解を導出する](/files/u4GrpQNvj0no1UcKFPjE)

#### 品質スコア（BLEUスコアによる自動評価）

| ベンダー   | BLEU（一般） | BLEU（法律） | BLEU（医療） | BLEU（技術） | 平均   |
| ------ | -------- | -------- | -------- | -------- | ---- |
| DeepL  | 42.3     | 38.1     | 35.7     | 44.2     | 40.1 |
| Google | 40.1     | 35.4     | 33.2     | 41.8     | 37.6 |
| AWS    | 37.8     | 31.2     | 29.8     | 38.4     | 34.3 |
| Azure  | 39.2     | 34.1     | 31.5     | 40.2     | 36.3 |

> **BLEUスコアとは** 機械翻訳の品質を自動評価する指標の一つです。0〜100の値をとり、100に近いほど参照訳（人間の翻訳）に近いことを示します。ただし、BLEUだけが絶対的な指標ではなく、COMET等の補完指標も重要です。詳しくは付録Aを参照。

![【Phase 3 結果②】BLEUスコアに基づく品質評価によりドメインごとに最適な翻訳ベンダーを選定する](/files/IxXSDEUJyhPz66ffEnip)

#### 意思決定への活用

このレポートを見て、たとえば以下のような意思決定ができます：

```
意思決定例：

1. コスト優先（大量処理バッチ）
   → Azure または AWS を選択（最安値）

2. 品質優先（法務・医療文書）
   → DeepL を選択（BLEUスコアが最も高い）

3. スピード優先（リアルタイム表示）
   → DeepL を選択（レイテンシが最小）

4. 日常業務（汎用）
   → Google を選択（コストと品質のバランス）

→ これらをルールとしてゲートウェイに組み込む
```

***

### CI/CDパイプラインとのAPIdog統合

#### CI/CDとは

> **CI/CD（継続的インテグレーション/継続的デリバリー）とは** コードの変更があるたびに自動でビルド・テスト・デプロイを行う仕組みです。GitHubやGitLabのコードプッシュをトリガーに、自動でテストが走ります。

APIdogはCLI（コマンドラインインターフェース）を提供しており、CI/CDパイプラインにテストを組み込めます。

#### GitHub Actionsとの統合例

```yaml
# .github/workflows/api-benchmark.yml
name: API Benchmark

# 毎日夜0時に自動実行 + 手動実行も可能
on:
  schedule:
    - cron: '0 15 * * *'   # UTC 15:00 = JST 0:00
  workflow_dispatch:

jobs:
  benchmark:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: APIdogCLIのインストール
        run: npm install -g apidog-cli

      - name: ベンチマークテストの実行
        run: |
          apidog run \
            --project-id ${{ secrets.APIDOG_PROJECT_ID }} \
            --test-suite "翻訳ベンダー品質ベンチマーク" \
            --env "production" \
            --reporter junit \
            --output test-results.xml
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
          DEEPL_API_KEY: ${{ secrets.DEEPL_API_KEY }}
          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}

      - name: テスト結果の公開
        uses: actions/upload-artifact@v3
        with:
          name: benchmark-results
          path: test-results.xml

      - name: Slackへ結果通知
        if: always()
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {
              "text": "翻訳ベンダーベンチマーク完了。結果を確認してください。"
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
```

このワークフローを設定すると：

1. 毎日深夜0時に自動でベンチマークテストが実行される
2. 結果がXML形式で保存される
3. Slackに通知が送られる
4. 結果を継続的にモニタリングし、ベンダーの品質変化を早期検知できる

#### ベンダー品質の変化検知

CI/CDで毎日ベンチマークを実行すると、以下のような変化を検知できます：

```
例: 2026年3月の変化
  3/1  DeepL BLEU 40.1 → 正常
  3/5  DeepL BLEU 35.2 → 低下検知！（アラート送信）
  3/6  DeepL APIバージョンアップを確認
  3/7  新バージョンのモデルで評価し直し → BLEU 43.8 に改善

→ ゲートウェイのDeepLアダプターをv2モデル対応に更新
```

このように、「定期的な自動ベンチマーク → 変化の検知 → ゲートウェイの調整」のサイクルを回すことで、常に最適な翻訳品質を維持できます。

![【Phase 3 統合】CI/CDパイプラインとの連携により日々の品質変動を自動検知しシステムの劣化を防ぐ](/files/36OywP5zLZZcRvstDPc0)

***

## まとめ

3つのフェーズとAPIdogの活用をまとめます：

| フェーズ                | 主な作業           | APIdogの活用機能                   | 成果物             |
| ------------------- | -------------- | ----------------------------- | --------------- |
| Phase 1: スキーマ設計     | 共通型・エンドポイント定義  | Design・Components             | OpenAPIスキーマ     |
| Phase 2: モック・ゲートウェイ | 並行開発の環境整備      | Mock Server・Docs・Team Sharing | 動くモック・チームドキュメント |
| Phase 3: 継続ベンチマーク   | 品質・コスト・速度の定期比較 | Test Suite・CI/CD連携            | 意思決定のためのデータ     |

このフェーズを繰り返すことで、グランドデザインは「設計書」から「生きているシステム」へと進化します。

![【サマリー】3つのフェーズを回すことで最適な品質とコストを維持し続ける](/files/MNYRC6L0hujqkxGIYEEp)

![【次のアクション】APIdogでスキーマ定義→モックサーバー起動→テストスイート試験運用の3ステップから着手する](/files/OOTpyiFn7fV0kede3ADJ)

***

→ [第15章 このグランドデザインが目指すもの](/ja/solutions/part7-future/ch15-vision.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://translationlab.gitbook.io/ja/solutions/part6-apidog/ch14-apidog-phases.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.