API Document Management and API Test
概要
API ドキュメントを適切に管理することは、開発者のオンボーディング、テスト、および統合にとって重要です。APIM を使用すると、OpenAPI スペックを添付したり、手動でドキュメントを定義したりして、インターフェース内で API をすぐにテストできます。このチュートリアルでは、デプロイされた API のドキュメントをアップロード/編集し、サンプル構成を使用してテストを実行する方法を示します。
前提条件
必要なもの:
- デプロイされた API バージョン (例: user-service-api v1.0)
- エディターまたは管理者権限を持つ APIM コンソールへのアクセス
- 手動で記述する場合は OpenAPI スペックファイルまたは API 定義の詳細
ステップバイステップ チュートリアル
ステップ 1. API バージョン詳細ページを開く
- API 管理に移動
- user-service-api を選択
- バージョン v1.0 を選択
ステップ 2. API ドキュメントをアップロードまたは編集する
2 つのオプションがあります:
オプション A: OpenAPI (YAML/JSON) をアップロード
- インポートをクリック
- OpenAPI 3.0 ファイル (例: user-service-v1.yaml) を選択してアップロード
- システムがすべてのエンドポイントと説明を解析して更新します
オプション B: 手動 API 定義
OpenAPI ファイルが利用できない場合:
- ドキュメントタブの下で編集をクリック
- 詳細を手動で追加: | フィールド | 例 | | --- | --- | | 概要 | ユーザーログインエンドポイント | | メソッド | POST | | パス | /login | | リクエストボディ | ユーザー名、パスワードを含む JSON | | レスポンス | 200 OK + JSON ボディ |
完了したら保存をクリックします。
ステップ 3. 組み込みテスターを使用して API をテストする
API バージン詳細ページのテストタブに移動:
| フィールド | 値 |
|---|---|
| 対象メソッド | POST |
| パス | /v1/login |
| ヘッダー | Content-Type: application/json |
ボディの例:
{
"username": "jane.doe",
"password": "test1234"
}
リクエストを送信をクリック
ステップ 4. テスト結果を確認する
期待されるレスポンス:
```json
{
"userId": "12345",
"token": "eyJhbGciOi..."
}
コンソールには次の内容が表示されます：
- HTTP ステータスコード (例: 200 OK)
- 所要時間
- リクエストおよびレスポンスボディ
一般的な問題とトラブルシューティング
| 問題 | 原因 | 解決策 |
|---|---|---|
| 無効な OpenAPI ファイル | 構文エラーまたはサポートされていないフィールド | Swagger Editor を使用して検証 |
| テストでの応答なし | パスが間違っているか、バックエンドが欠落している | Gateway ルートパスとバックエンドの健康状態を再確認 |
| 401 Unauthorized | API キーまたは認証ポリシーが欠落 | 認証ヘッダーを設定するか、一時的に認証を無効にする |
| 415 Unsupported Media Type | Content-Type が欠落または間違っている | ボディリクエストには application/json を使用 |
ベストプラクティス
- 正確なドキュメントのために、常に検証済みの OpenAPI スペックをアップロードする
- 各エンドポイントに対して例のリクエスト/レスポンスを追加する
- 外部の消費者と API を共有する前に、組み込みテスターを使用する
- 成功ケースだけでなく、エラー応答 (4xx/5xx) を文書化する
- API ライフサイクルに合わせて API ドキュメントをバージョン管理する