APIナレッジベース OpenAPI（Swagger）

完全解説：Swaggerでリクエストヘッダの書き方は？

SwaggerはAPI業界のデファクトスタンダードとして広く利用されているOpenAPI仕様の実装です。APIを定義したり、テストしたりする際、多くの場合、Swaggerでリクエストヘッダーを書く必要があります。それでは、Swaggerでリクエストヘッダを書くには、どうしたら良いですか？本文では、Swaggerでリクエストヘッダの書き方を皆さんに紹介していきたいと思います。

shimizu chioka

Updated on 2024年8月7日 4分読む

Swaggerとリクエストヘッダについて

そもそもSwaggerとリクエストヘッダとはなんですか？本文では、まず両者の基本情報を皆さんに紹介していきたいと思います。

Swaggerとは

Swaggerとは、APIの設計・説明・文書化を行うためのオープンソースフレームワークです。 OpenAPI Specification (旧 Swagger Specification) と呼ばれる形式でAPIを定義することができます。近年ではOpenAPI Initiativeによってオープン標準仕様「OpenAPI Specification」が策定・管理されており、Swaggerはその代表的な実装の1つとして位置づけられています。APIの設計・ドキュメンテーションにおいて業界標準の地位を築いていると言えます。主な特徴は以下の通り：

YAMLやJSON形式でAPIを定義できるため、開発者にとって親しみやすい
APIの仕様をインタラクティブなドキュメントとして自動生成できる
クライアントSDKのコード生成に対応している
モックサーバーを生成できるためAPIのテストがしやすい

Swaggerを使用することで、APIのドキュメント作成やクライアントとのインテグレーションを容易に行うことができます。

リクエストヘッダとは

リクエストヘッダ(request header)とは、HTTPやHTTPSなどのプロトコルでクライアントがサーバーにリクエストを送信する際に、リクエストメッセージの先頭に付加されるメタデータのことです。

主なリクエストヘッダには以下のようなものがあります。

User-Agent - クライアントのアプリケーション名やバージョン情報
Accept - クライアントが受け入れ可能なコンテンツの種類
Authorization - 認証トークンによる認証
Content-Type - リクエストボディのコンテンツタイプ
Content-Length - リクエストボディの長さ

リクエストヘッダはオプション指定が可能で、サーバー側でヘッダ値のチェックを行うことができます。またクライアントの状態をサーバー側に伝える情報としても利用されます。APIを設計する際には、リクエストから期待するヘッダの指定とそのチェックロジックを実装する必要があります。

Swaggerとリクエストヘッダの関連

以上より、Swaggerとリクエストヘッダの関連を容易にまとめることができるのだろう。それでは、Swaggerとリクエストヘッダーの関連について、以下のようにまとめてみました。

SwaggerではYAML/JSON形式でリクエストヘッダーを定義できる。name, required, schema等でヘッダーのスキーマを記述。
定義したリクエストヘッダーはインタラクティブドキュメントに表示される。API利用者にヘッダーの役割が理解しやすい。
Swagger Codegen等を利用して、定義に基づいたAPIクライアントコードを自動生成できる。
Swaggerを利用するフレームワークでは、リクエスト受信時にヘッダーをスキーマ通りに検証できる。
OpenAPI v3からリクエストヘッダーに対してJSON Schemaによる検証機能が強化された。

Swaggerはリクエストヘッダーの定義とそれに基づく利用を強力にサポートしているといえます。APIのドキュメント/コード/テストの一貫性が保たれます。

Swaggerでリクエストヘッダを書く方法

それでは、Swaggerでリクエストヘッダをどうやって書けば良いのでしょうか？Swaggerは普段YAMLとJSONといった2つの記述フォーマットしかサポートできないので、次は、この2つのフォーマットでリクエストヘッダを書く方法を皆さんに紹介しようと思います。

SwaggerのYAMLでリクエストヘッダを定義

Swaggerでリクエストヘッダーを定義するには、pathsオブジェクトの中で対象のパスを定義した後にparameters配列を使用します。

paths:
  /users:
    get:
      parameters:
        - in: header
          name: User-Agent
          schema:
            type: string
          required: true
          description: クライアントのブラウザとOS情報
        - in: header
          name: Accept-Language 
          schema:
            type: string
          description: 受け入れ可能な自然言語

このようにparametersのin属性にheaderを指定し、nameにヘッダーの名前、schemaに型やその他のスキーマを定義します。requiredで必須項目かどうかも指定できます。さらにdescriptionでそのヘッダーの説明を記載することも可能です。

この定義により、クライアントはdocument内のヘッダー定義を見てリクエスト時に送信が必要なヘッダーを把握できるようになります。

JSONでリクエストヘッダの書き方

SwaggerでJSON形式でリクエストヘッダーを定義する場合は次のようにします。

"/users": {
  "get": {
    "parameters": [
      {
        "name": "User-Agent",
        "in": "header",
        "description": "クライアントのブラウザとOS情報", 
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      {  
        "name": "Accept-Language",
        "in": "header",
        "description": "受け入れ可能な自然言語",
        "schema": {
          "type": "string"
        }
      }
    ]
  }
}

pathsプロパティ以下にエンドポイントのパスを定義し、get、postなどのメソッドを定義します。parameters配列でヘッダーを定義していき、nameにヘッダー名、inにheader、schemaに型を指定します。また、requiredやdescriptionも指定できます。

以上のようにすれば、JSON形式でもYAMLと同様にリクエストヘッダーを定義できます。

Apidogでリクエストヘッダーを簡単に記述・確認

それでは、より簡単なリクエストヘッダの記述方法やテスト方法はありませんか？Apidogは、非常に優れているAPI設計・テストツールとして、APIを定義する際にリクエストヘッダを簡単に記述することもできますし、API送受信のときにヘッダーを編集したり、リクエストヘッダーとレスポンスヘッダーを確認したりすることもできます。

button

Apidogを開き、HTTPプロジェクトを新規に作成すると、次の操作を参照したら、リクエストヘッダを簡単にカスタマイズすることが可能です。

APIリクエストヘッダの定義

「＋」ボタンをクリックして、APIを新規に作成すると、直感的なUIで新しいAPIを定義することができるようになります。リクエストヘッダを定義する必要がある場合、「Requestパラメータ」で「Header」タブに切り替えて、パラメータ名とパラメータ値を入力するだけで簡単に定義できます。

リクエストヘッダーのカスタマイズ

右下のスイッチをクリックして、「デバッグ」モードに切り替えると、「＋」ボタンをクリックして、リクエストを新規に作成し、必要なリクエスト情報を記入して、「Headers」タブに切り替えます。ここで、「パラメータ名」の入力ボックスをクリックすると、利用可能なフィールドが表示されます。そこから必要なパラメータを選択して、パラメータ値を入力した上、「送信」ボタンをクリックしてAPIの疎通確認が行えます。

リクエストヘッダーとレスポンスヘッダーの確認

上記の手順を参照して、必要な情報を全て記入すると、「送信」ボタンをクリックして、リクエストを送信します。ここで、サーバーからレスポンスを取得できます。レスポンスヘッダーを確認するには、レスポンスエリアで「Headers」タブをクリックしてください。

また、「実際のRequest」タブに切り替えると、実際に送信したリクエストヘッダーの情報を確認することもできます。