# 第13章 APIdogとグランドデザインの接点
> **ナビゲーション**
>
> * 前の章: [第12章 ゲートウェイAPIの設計](/ja/solutions/part5-integration/ch12-gateway-api.md)
> * 次の章: [第14章 設計フェーズ別のAPIdog活用](/ja/solutions/part6-apidog/ch14-apidog-phases.md)
***
## この章で学ぶこと
ここまでの章で、翻訳・STT・TTSなどの言語サービスAPIを「共通スキーマ」で統合するグランドデザインを学んできました。しかし「設計」はドキュメントに書いただけでは機能しません。チーム全員が同じ定義を参照し、テストし、反復改善できる「ツール」が必要です。
この章では **APIdog** というツールを紹介し、グランドデザインの「設計の錨（いかり）」として活用する方法を解説します。
***
## 13.1 APIdogを「設計の錨」として使う
### APIdogとは何か
**APIdog**（エーピーアイドッグ）は、API開発のライフサイクル全体を一つのツールでカバーするオールインワン・プラットフォームです。
> **初めての方へ** 「API開発ツール」と聞いてピンとこない方のために、身近な例で説明します。 レストランを設計するとき、「メニュー（何を提供するか）」「調理マニュアル（どう作るか）」「試食（品質確認）」「お客様への案内（ドキュメント）」を別々の冊子で管理すると混乱します。APIdogは、これらを一冊のデジタルブックにまとめたようなものです。
APIdogは以下のツールを統合しています：
| 機能 | 旧来の相当ツール | 説明 |
| -------- | ------------------- | ----------------------- |
| API設計 | Swagger Editor | OpenAPI形式でAPIを設計・編集する |
| ドキュメント生成 | Redoc / Swagger UI | 設計から自動でAPIドキュメントを生成する |
| モックサーバー | json-server | 実装がなくてもAPIの動作をシミュレートする |
| APIテスト | Postman | リクエストを送ってレスポンスを確認・自動化する |
| チーム共有 | Confluence + GitHub | チーム全員が同じ定義を参照・編集できる |
つまり、**Postman + Swagger + モックサーバー + チーム共有** を一つにまとめたツールと理解してください。
***
### 「設計の錨」という概念
プロジェクトが大きくなると、「どれが最新のAPI定義か」「フロントエンドとバックエンドでスキーマが食い違っている」「ドキュメントが古いまま」といった問題が起きます。
**設計の錨（Design Anchor）** とは、チーム全員が参照する「唯一の真実（Single Source of Truth）」となる場所のことです。
```mermaid
flowchart TD
A["⚓ APIdog（設計の錨）
APIスキーマ定義"]
B["🖥️ フロントエンドチーム"]
C["⚙️ バックエンド開発チーム"]
D["🧪 モックサーバー / テスト"]
A --> B
A --> C
B --> D
C --> D
```
APIdogをプロジェクトの「錨」に置くと：
1. **全員が同じスキーマを見る** ── ドキュメントとコードの乖離がなくなる
2. **変更が即座に伝わる** ── スキーマを変更すると、ドキュメント・モック・テストがすべて追従する
3. **実装前にテストできる** ── モックサーバーで動作確認してから本実装に進める
***
### API-First開発の考え方
従来の開発は「コードを書いてからAPIドキュメントを後付け」でした。**API-First（API ファースト）** は逆の発想です。
```
従来（Code-First）:
実装 → ドキュメント化 → テスト → …（ドキュメントが追いつかない）
API-First:
スキーマ設計 → モック動作確認 → 並行開発 → テスト → 実装
```
言語APIワールドのグランドデザインにおいても、API-Firstは重要です。なぜなら：
* **ベンダーが変わってもスキーマは変わらない** ── DeepLからGoogle翻訳に切り替えるとき、ゲートウェイのスキーマは同じまま保たれる
* **発注者・受注者が共通言語を持てる** ── 言語サービスプロバイダー（LSP）との要件定義で「このエンドポイントにこのリクエストを送る」と明示できる
* **品質比較が可能になる** ── 同一スキーマで複数ベンダーをテストできる
***
### APIdogの主要機能
#### 1. API設計（Design）
OpenAPI 3.x形式でAPIを視覚的に設計できます。コードを書かずにGUIで操作でき、同時にYAML/JSONの生データも編集できます。
```yaml
# APIdogで設計したAPIスキーマの例（OpenAPI 3.0形式）
paths:
/translate:
post:
summary: テキスト翻訳
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TranslationRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TranslationResponse'
```
#### 2. ドキュメント生成（Docs）
スキーマを設計すると、**自動的に**美しいAPIドキュメントが生成されます。URLを共有するだけで、非エンジニアを含む全員がドキュメントを参照できます。
#### 3. モックサーバー（Mock）
実装が完了していなくても、スキーマに基づいてモックサーバーが自動起動します。フロントエンドチームは「バックエンドの実装待ち」なしに開発を進められます。
#### 4. テスト（Testing）
リクエストを送ってレスポンスを検証する「APIテスト」をGUIで作成・自動化できます。テスト結果はレポートとして出力されます。
#### 5. チーム共有（Collaboration）
チームメンバーを招待すると、全員が同一プロジェクトのスキーマを参照・編集できます。変更履歴も管理されます。
***
## 13.2 既存ベンダー仕様のインポートと差異の可視化
### なぜインポートするのか
DeepL・Google・AWSなどの翻訳ベンダーは、それぞれ独自のAPI仕様を持っています。これらをAPIdogにインポートすることで、**横並びで比較できる状態**にします。
> **OpenAPI仕様（スペック）とは** OpenAPI（旧称Swagger）は、APIの仕様を記述するための標準フォーマット（YAML/JSON形式）です。「このURLにどんなパラメータを送ると、どんなレスポンスが返るか」を機械可読な形式で記述します。多くのベンダーがこの形式で公式仕様を公開しています。
***
### インポートの手順概要
APIdogへのインポートは以下の手順で行います：
1. **インポート元を用意する**
* 公開されているOpenAPI仕様ファイル（.yaml / .json）のURLまたはファイルを用意
* ベンダーのGitHubリポジトリや開発者ポータルから取得
2. **APIdogでプロジェクトを作成**
* 「新しいプロジェクト」を作成（例：「言語APIワールド 翻訳ゲートウェイ」）
3. **インポート実行**
* メニューから「インポート」→ 「OpenAPI/Swagger」を選択
* URLまたはファイルを指定して読み込む
4. **確認・クリーンアップ**
* インポートされたエンドポイントを確認
* 重複や不要な項目を整理
***
### インポート後に分かること
各ベンダーをインポートして並べると、以下の違いが一目瞭然になります：
#### エンドポイント数の比較
| ベンダー | 翻訳エンドポイント数 | 言語検出 | ドキュメント翻訳 | その他 |
| ------------------------ | --------------------- | ---- | -------- | -------- |
| DeepL | 1（POST /translate） | 1 | 1（Pro限定） | 用語集管理 5個 |
| Google Cloud Translation | 3（Basic/Advanced/バッチ） | 1 | 1 | 言語一覧 1個 |
| AWS Translate | 2（同期/非同期） | 1 | 1 | 用語集管理 4個 |
| Azure Translator | 4（翻訳/音訳/辞書/言語） | 1 | 1 | 文章分割 1個 |
#### 認証方式の差異
| ベンダー | 認証方式 | ヘッダー名 |
| ---------------- | ----------------- | ------------------------------------- |
| DeepL | APIキー | `Authorization: DeepL-Auth-Key {key}` |
| Google Cloud | OAuth 2.0 / APIキー | `Authorization: Bearer {token}` |
| AWS Translate | AWS Signature V4 | `X-Amz-*` 系ヘッダー |
| Azure Translator | APIキー | `Ocp-Apim-Subscription-Key` |
この差異を見るだけで、「共通ゲートウェイの認証レイヤーで吸収すべき差異」が明確になります。
#### リクエスト・レスポンスのスキーマ差異
翻訳リクエストの基本構造を比べると：
```json
// DeepLの場合
{
"text": ["Hello, world!"],
"target_lang": "JA"
}
// Google Cloud Translationの場合
{
"contents": ["Hello, world!"],
"targetLanguageCode": "ja",
"mimeType": "text/plain"
}
// AWS Translateの場合（パラメータ名が異なる）
{
"Text": "Hello, world!",
"TargetLanguageCode": "ja",
"SourceLanguageCode": "en"
}
```
フィールド名・大文字小文字・配列 vs 文字列など、細かい差異が多数あります。これらを**APIdogのUI上で並べて確認**できることが、共通スキーマ設計の出発点になります。
***
### 差異の可視化から共通スキーマ設計へ
インポートした複数ベンダーの仕様を比較することで、**共通化できる部分とベンダー固有の部分**が見えてきます：
```
共通化できる部分（ゲートウェイスキーマに組み込む）:
✓ テキストコンテンツ（翻訳するテキスト）
✓ ソース言語・ターゲット言語（BCP-47形式に統一）
✓ 品質ティア（speed / balanced / quality）
✓ エラーレスポンス形式
ベンダー固有の部分（アダプター層で吸収する）:
✗ 認証ヘッダーの形式
✗ フィールド名の命名規則
✗ 非同期処理の実装方法
✗ ベンダー固有のオプション（形式性レベル等）
```
***
### APIdogのComponents機能で共通型を定義する
APIdogには **Components（コンポーネント）** という機能があります。OpenAPIのComponents Objectに対応し、**再利用可能な型（スキーマ）** を定義できます。
グランドデザインで登場した共通型をComponentsに定義しておくと、すべてのエンドポイントで同じ型を参照できます：
```yaml
# Componentsに定義する共通型の例
components:
schemas:
# 翻訳リクエストの共通スキーマ
TranslationRequest:
type: object
required:
- content
- targetLanguage
properties:
content:
type: string
description: 翻訳するテキスト
sourceLanguage:
type: string
description: "ソース言語（BCP-47形式、例: ja, en-US）"
targetLanguage:
type: string
description: "ターゲット言語（BCP-47形式、例: en, ja）"
qualityTier:
$ref: '#/components/schemas/QualityTier'
# 品質ティアの共通定義
QualityTier:
type: string
enum:
- speed
- balanced
- quality
description: |
- speed: 高速・低コスト（機械翻訳そのまま）
- balanced: バランス型（デフォルト）
- quality: 高品質・人間レビュー含む
# 共通エラーレスポンス
ErrorResponse:
type: object
required:
- code
- message
properties:
code:
type: string
message:
type: string
details:
type: object
```
この **`$ref`（リファレンス）** 機能により、一度定義した型を複数のエンドポイントで使い回せます。`QualityTier` の定義を変更すれば、参照しているすべての箇所に反映されます。
***
## まとめ
この章では以下を学びました：
* **APIdogはAPI開発のオールインワンツール**。設計・ドキュメント・モック・テスト・チーム共有を一元管理する
* **「設計の錨」として機能**させることで、チーム全員が同一のスキーマを参照し、乖離を防ぐ
* **API-First開発**により、実装前にスキーマを合意し、並行開発を可能にする
* **ベンダー仕様のインポートと比較**で、共通化すべき差異が可視化される
* **Components機能**で共通型を定義し、全エンドポイントで再利用できる
次章では、このAPIdogを使って設計フェーズごとにどう活用するかを具体的に解説します。
***
→ [第14章 設計フェーズ別のAPIdog活用](/ja/solutions/part6-apidog/ch14-apidog-phases.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/ch13-apidog-overview.md?ask=
```
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.