API サーバとベースパス

すべてのAPIエンドポイントはベースURLを基準とします。たとえば、ベースURLがhttps://api.example.com/v1である場合、/usersエンドポイントはhttps://api.example.com/v1/usersを指します。

1
https://api.example.com/v1/users?role=admin&status=active
2
\________________________/\____/ \______________________/
3
server URL       endpoint    query parameters
4
path

OpenAPI 3.0では、servers配列を使用して、APIの1つ以上のベースURLを指定します。serversは、OpenAPI 2.0で使用されていたhost、basePath、およびschemesキーワードを置き換えます。各サーバーにはurlと、オプションのMarkdown形式のdescriptionがあります。

1
servers:
2
  - url: https://api.example.com/v1    # The "url: " prefix is required

複数のサーバーを持つこともできます。たとえば、本番環境とサンドボックス環境などです。

1
servers:
2
  - url: https://api.example.com/v1
3
    description: Production server (uses live data)
4
  - url: https://sandbox-api.example.com:8443/v1
5
    description: Sandbox server (uses test data)

サーバーURL形式

サーバーURLの形式はRFC 3986に準拠しており、通常は次のようになります。

1
scheme://host[:port][/path]

ホストは名前またはIPアドレス（IPv4またはIPv6）にすることができます。OpenAPI 2.0のWebSocketスキームws://とwss://もOpenAPI 3.0でサポートされています。有効なサーバーURLの例:

1
https://api.example.com
2
https://api.example.com:8443/v1/reports
3
https://:3025/v1
4
http://10.0.81.36/v1
5
ws://api.example.com/v1
6
wss://api.example.com/v1
7
/v1/reports
8
/
9
//api.example.com

サーバーURLが相対パスの場合、指定されたOpenAPI定義ファイルがホストされているサーバーに対して解決されます（詳細については以下を参照）。注：サーバーURLにはクエリ文字列パラメーターを含めることはできません。たとえば、これは無効です:

1
https://api.example.com/v1?route=

servers配列が指定されていないか空の場合、サーバーURLはデフォルトで/になります。

1
servers:
2
  - url: /

サーバーのテンプレート化

サーバーURLの任意の部分（スキーム、ホスト名またはその一部、ポート、サブパス）は、変数を使用してパラメーター化できます。変数はサーバーURL内で中括弧{}で示されます。例:

1
servers:
2
  - url: https://{customerId}.saas-app.com:{port}/v2
3
    variables:
4
      customerId:
5
        default: demo
6
        description: Customer ID assigned by the service provider
7
      port:
8
        enum:
9
          - '443'
10
          - '8443'
11
        default: '443'

パスパラメーターとは異なり、サーバー変数はschemaを使用しません。代わりに、文字列であると想定されます。変数は任意の値を保持できますが、enumに制限することもできます。いずれの場合も、default値が必須であり、クライアントが値を指定しない場合に使用されます。変数descriptionはオプションですが、あると便利で、リッチテキスト形式のMarkdown（CommonMark）をサポートします。サーバーのテンプレート化の一般的なユースケース:

複数のプロトコル（HTTPとHTTPSなど）を指定する。
各顧客が独自のサブドメインを持つSaaS（ホスト型）アプリケーション。
異なる地理的地域にある地域サーバー（例：Amazon Web Services）。
SaaSおよびオンプレミスAPI用の単一API定義。

例

HTTPSとHTTP

1
servers:
2
  - url: http://api.example.com
3
  - url: https://api.example.com

またはテンプレートを使用する

1
servers:
2
  - url: '{protocol}://api.example.com'
3
    variables:
4
      protocol:
5
        enum:
6
          - http
7
          - https
8
        default: https

注：これら2つの例は意味的に異なります。2番目の例はHTTPSサーバーを明示的にdefaultとして設定していますが、最初の例にはデフォルトサーバーがありません。

本番環境、開発環境、ステージング環境

1
servers:
2
  - url: https://{environment}.example.com/v2
3
    variables:
4
      environment:
5
        default: api    # Production server
6
        enum:
7
          - api         # Production server
8
          - api.dev     # Development server
9
          - api.staging # Staging server

SaaSとオンプレミス

1
servers:
2
  - url: "{server}/v1"
3
    variables:
4
      server:
5
        default: https://api.example.com # SaaS server

異なる地理的地域向けのリージョンエンドポイント

1
servers:
2
  - url: https://{region}.api.cognitive.microsoft.com
3
    variables:
4
      region:
5
        default: westus
6
        enum:
7
          - westus
8
          - eastus2
9
          - westcentralus
10
          - westeurope
11
          - southeastasia

サーバーの上書き

グローバルなservers配列は、パスレベルまたは操作レベルで上書きできます。これは、一部のエンドポイントがAPIの他の部分とは異なるサーバーまたはベースパスを使用する場合に便利です。一般的な例としては、次のものがあります。

ファイルのアップロードおよびダウンロード操作の異なるベースURL、
非推奨だがまだ機能しているエンドポイント。

1
servers:
2
  - url: https://api.example.com/v1
3

4
paths:
5
  /files:
6
    description: File upload and download operations
7
    servers:
8
      - url: https://files.example.com
9
        description: Override base path for all operations with the /files path
10
    ...
11

12
/ping:
13
    get:
14
      servers:
15
        - url: https://echo.example.com
16
          description: Override base path for the GET /ping operation

相対URL

servers配列内のURLは、/v2のように相対パスにすることができます。この場合、URLは指定されたOpenAPI定義をホストするサーバーに対して解決されます。これは、顧客自身のサーバーにホストされているオンプレミスインストールで役立ちます。たとえば、https://:3001/openapi.yamlでホストされている定義がurl: /v2を指定している場合、urlはhttps://:3001/v2に解決されます。相対URL解決ルールはRFC 3986に準拠しています。さらに、API定義内のほとんどすべての他のURL（OAuth 2フローエンドポイント、termsOfService、外部ドキュメントURLなど）は、サーバーURLに対して相対的に指定できます。

1
servers:
2
  - url: https://api.example.com
3
  - url: https://sandbox-api.example.com
4

5
# Relative URL to Terms of Service
6
info:
7
  version: 0.0.0
8
  title: test
9
  termsOfService: /terms-of-use
10

11
# Relative URL to external documentation
12
externalDocs:
13
  url: /docs
14
  description: Find more info here
15

16
# Relative URLs to OAuth2 authorization and token URLs
17
components:
18
  securitySchemes:
19
    oauth2:
20
      type: oauth2
21
      flows:
22
        authorizationCode:
23
          authorizationUrl: /oauth/dialog
24
          tokenUrl: /oauth/token

複数のサーバーを使用する場合、相対URLで指定されたリソースはすべてのサーバーに存在することが期待されることに注意してください。

参照

サーバーオブジェクト

URL内の相対参照

お探しのものが見つかりませんでしたか？コミュニティに尋ねる間違いを見つけましたか？お知らせください