MENU

OpenAPIの設定でのURLとパスの違い

OpenAPIの設定でのURL（Uniform Resource Locator）とパスの違いを説明します。

URL（Uniform Resource Locator）

URLは、インターネット上の特定のリソース（ウェブページ、画像、APIエンドポイントなど）を指定するためのアドレスです。URLは次の要素で構成されます：

  1. スキーム（Scheme）: 通信プロトコルを示します（例：http, https, ftp）。
  2. ホスト名（Hostname）: ドメイン名またはIPアドレスです（例：www.example.com）。
  3. ポート番号（Port Number）: 通常省略されますが、必要な場合はホスト名の後にコロンとともに指定されます（例：https://www.example.com:443）。
  4. パス（Path）: サーバー上の特定のリソースへのパスです（例：/path/to/resource）。
  5. クエリパラメータ（Query Parameters）: 追加のデータをURLに含めるためのものです（例：?key1=value1&key2=value2）。
  6. フラグメント識別子（Fragment Identifier）: リソース内の特定のセクションを示します（例：#section1）。

パス（Path）

パスは、URLの一部であり、特定のリソースやエンドポイントを示します。サーバーのベースURLからの相対的な位置を示すものです。パス自体はプロトコルやホスト名を含まないため、ベースURLと組み合わせて使用されます。

例

フルURL: https://api.example.com/v1/users?id=1234

このURLの各部分を分解すると：

  1. スキーム: https
  2. ホスト名: api.example.com
  3. パス: /v1/users
  4. クエリパラメータ: ?id=1234

OpenAPIの設定での使用方法

OpenAPI仕様では、ベースURLとパスを別々に定義します。

ベースURL

serversセクションに含まれ、プロトコルとホスト名を指定します。

servers:
  - url: https://api.example.com
    description: Main API server

パス

pathsセクションに含まれ、特定のエンドポイントの相対パスを指定します。

paths:
  /v1/users:
    get:
      summary: Retrieve users
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string

結論

URLはインターネット上のリソースを一意に識別するための完全なアドレスであり、パスはその一部としてサーバー内の特定のリソースを指します。OpenAPI仕様では、これらを適切に分割して定義することで、APIエンドポイントを正確に指定します。

コラム