メインコンテンツまでスキップ

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. テスト結果を確認する​

期待されるレスポンス：

{
"userId": "12345",
"token": "eyJhbGciOi..."
}

コンソールには次の内容が表示されます：

  • HTTPステータスコード（例：200 OK）
  • 所要時間
  • リクエストおよびレスポンスボディ

一般的な問題とトラブルシューティング​

問題原因解決策
無効なOpenAPIファイル構文エラーまたはサポートされていないフィールドSwagger Editorを使用して検証
テストでのレスポンスなしパスが間違っているか、バックエンドが欠落しているゲートウェイルートパスとバックエンドの健康状態を再確認
401 UnauthorizedAPIキーまたは認証ポリシーが欠落認証ヘッダーを設定するか、一時的に認証を無効にする
415 Unsupported Media TypeContent-Typeが欠落または間違っているボディリクエストにはapplication/jsonを使用

ベストプラクティス​

  • 正確なドキュメントのために常に検証済みのOpenAPI仕様をアップロードする
  • 各エンドポイントに対して例のリクエスト/レスポンスを追加する
  • 外部の消費者とAPIを共有する前に組み込みテスターを使用する
  • 成功ケースだけでなく、エラーレスポンス（4xx/5xx）も文書化する
  • APIライフサイクルに合わせてAPIドキュメントをバージョン管理する