【技術ブログ】OpenAPIのテストとは？：OpenAPIを使用した設計の知識 vol.3

開発エンジニアのNAHO.Sです。

前回記事（【技術ブログ】OpenAPIの書き方とは？：OpenAPIを使用した設計の知識 vol.2）では、OpenAPIの基本的な書き方や主要な定義要素についてご紹介しました。

今回は、書いたOpenAPI定義書が正しいかチェックし、実際に動作を確認する「OpenAPIのテスト」についてご紹介いたします。

5. テストの目的と基本的な流れ

OpenAPI定義書をテストする目的は、「定義内容が仕様通りであること」、そして「実際のAPIと正しく連携できること」を保証することです。

テストは主に以下の基本的な流れで行います。

1. 定義書をツールでプレビュー表示する
2. 構文エラーがないかを確認する
3. モックサーバーや実際のAPIサーバーと接続して通信テストを行う

5.1. テストで確認すべき重要ポイント

テスト時には、特に以下のポイントを重点的に確認します。

• 型と構造の整合性
  「数字（integer）で送るはずが、誤って文字列（string）になっていないか？」など、定義と実際のデータ構造が一致しているかを確認します。
• 必須項目（required）のチェック漏れ防止
  「リクエスト時に必ず必要なデータ」が漏れなくrequiredに指定されているかを確認します。
• レスポンスコードの網羅
  正常系の「200」だけでなく、エラー系の「400」などの定義を設けることで、開発者が例外発生時の挙動をあらかじめ把握できるようになります。
  

6. Swagger Viewerを活用したテスト準備 

OpenAPIの定義書（YAMLやJSON）は、そのままの状態では単なるテキストファイルです。これだけでは「パスの構造が正しいか」や「レスポンスのデータ形が直感的か」を判断するのが難しく、見落としが発生しやすくなります。

そこで今回は、Visual Studio Code（VS Code）の拡張機能である「Swagger Viewer」を活用して動作確認を行います。

参考：Swagger Viewer

Swagger Viewerを使用すると、記述したコードをリアルタイムで人間が読みやすいドキュメント形式（Swagger UI）へ可視化してくれます。これにより、視覚的に構造を把握しながら、リアルタイムで構文エラーを検出・修正できるようになります。

※あらかじめVS Codeの拡張機能画面からインストールを完了させておきましょう。

7. API定義書の検証と動作確認の実践

ここからは、実際にSwagger Viewerを使って定義書を検証し、動作確認を行う手順を解説します。
 

7.1. テスト用のサンプル定義書

vol.2で作成した「商品管理API」のJSON定義書をそのまま使用して、テストの流れを体験してみます。

{
    "openapi": "3.1.0",
    "info": {
        "title": "商品管理API",
        "description": "商品管理のAPI",
        "version": "1.0.0"
    },
    "servers": [
        {
            "url": "http://localhost:8080"
        }
    ],
    "tags": [
        {
            "name": "Products",
            "description": "商品"
        }
    ],
    "paths": {
        "/product/{productId}": {
            "get": {
                "summary": "商品情報取得",
                "tags": [
                    "Products"
                ],
                "deprecated": false,
                "operationId": "getProduct",
                "parameters": [
                    {
                        "name": "productId",
                        "in": "path",
                        "description": "商品ID",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "商品情報取得成功",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Product"
                                },
                                "example": {
                                    "id": 1223,
                                    "name": "Sample Product",
                                    "price": 1000
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "リクエストエラー"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Product": {
                "type": "object",
                "required": [
                    "id"
                ],
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "string"
                    },
                    "price": {
                        "type": "integer"
                    }
                }
            }
        }
    }
}

7.2. 定義書のプレビューとエラーチェック

1. VS Code上で上記内容を記述したファイル（.json）を開きます。
2. Swagger Viewerを立ち上げます。
   （ショートカットキー：Alt + Shift + P）
    
3. プレビュー画面にドキュメントが表示されれば成功です。

もし画面が正常に表示されない場合は、定義書の構文構造のどこかにエラーがあります。

不備のある部分にはSwagger Viewerによって赤い波線が表示されますので、波線のある行を中心に修正を行いましょう。

7.3. ドキュメント内容の確認

プレビュー上の「GET」を展開すると、定義書に記載したパラメータ（productId）やレスポンス仕様が一覧表示されます。

• 必須マークのつけ忘れがないか
• データ型（integerやstring）に誤りがないか

など、ドキュメントとして不備がないかを最終見直しします。

 7.4. サーバーと接続した通信・動作確認

ドキュメントのチェックが終わったら、実際にAPIを呼び出すテストを行います。

本物のサーバーが未完成な場合でも、「Prism」などのモックサーバーツールを使用すれば、定義書から即座に「仮のAPIサーバー」を起動して通信テストを行うことができます（本物サーバー完成後はそちらに接続します）。
 

1. サーバー（本物またはモック）を起動します。
2. 定義書内のservers項目のurlをサーバーのアドレス（例：http://127.0.0.1:4010）に書き換えます。

"servers": [
    {
        "url": "http://127.0.0.1:4010"
    }
]

3. Swagger Viewerの画面上で「Try it out」ボタンをクリックします。

   

    
    

4. 商品ID（productId）に任意の値を入力し、「Execute」ボタンをクリックして実行します。

   

    

5. 返ってきたレスポンス結果が、定義書で指定したexampleの内容と一致していることを確認します。

   

 まとめ

全3回にわたってお届けした「OpenAPIを使用した設計の知識」シリーズですが、今回はOpenAPI定義書のテストと動作確認の手順をご紹介しました。

VS Code拡張機能の「Swagger Viewer」を活用することで、定義書を直感的なドキュメントとしてプレビュー表示し、記載エラーを素早くチェックできます。
さらに servers のURLを切り替えるだけで、モックサーバーや実サーバーへのリクエスト・レスポンス確認までスムーズに行えます。

今回は概要のみ触れましたが、「Prism」のようなツールを導入することで、定義書1つで手軽にテスト用疑似環境（モック）を作成可能です。開発効率向上にも役立ちますので、興味のある方はぜひ試してみてください。

当社では、Google 関連のサービスを活用したアプリケーション開発を行い、Google Cloud ・ Google Workspace をより便利にご利用いただけるようお手伝いしています。Google プロダクトを利用する上でのご相談やご不明点がありましたら、お気軽にお問い合わせください。

※本記事の情報および画像は 2026/08/14 時点での仕様のものです。