APIホストとベースパス

OAS 2 このページは、OpenAPI Specification ver. 2 (旧Swagger) に適用されます。最新バージョンについては、OpenAPI 3ページをご覧ください。

APIホストとベースURL

REST APIには、エンドポイントパスが追加されるベースURLがあります。ベースURLは、API仕様のルートレベルにある`schemes`、`host`、`basePath`によって定義されます。

host: petstore.swagger.io
basePath: /v2
schemes:
  - https

すべてのAPIパスはこのベースURLからの相対パスです。たとえば、`/users`は実際には`<scheme>://<host>/<basePath>/users`を意味します。

URL structure

schemes

`schemes`は、APIで使用される転送プロトコルです。Swaggerは、`http`、`https`、およびWebSocketスキーム（`ws`と`wss`）をサポートしています。YAMLの他のリストと同様に、スキームはリスト構文を使用して指定できます。

schemes:
  - http
  - https

または、配列リテラル構文を使用します。

schemes: [http, https]

`schemes`が指定されていない場合、API仕様を提供するために使用されるスキームがAPI呼び出しに使用されます。

host

`host`は、APIを提供するホストのドメイン名またはIPアドレス（IPv4）です。スキームのデフォルトポート（HTTPの場合は80、HTTPSの場合は443）と異なる場合は、ポート番号を含めることができます。これはホストのみで、 *http(s)://* またはサブパスを含めないでください。有効なホスト

api.example.com
example.com:8089
93.184.216.34
93.184.216.34:8089

正しくない例

http://api.example.com
example.com/api/v1

`host`が指定されていない場合、APIドキュメントが提供されているのと同じホストであると想定されます。

basePath

`basePath`は、ホストルートを基準としたすべてのAPIパスのURLプレフィックスです。スラッシュ `/` で始める必要があります。 `basePath`が指定されていない場合、デフォルトは `/` です。つまり、すべてのパスはホストルートから始まります。有効なベースパス

/v2
/api/v2
/

正しくない例

v2

ホストとスキームの省略

より動的な関連付けのために、`host`と`schemes`を省略できます。この場合、APIドキュメントを提供するために使用されるホストとスキームがAPI呼び出しに使用されます。たとえば、Swagger UIベースのドキュメントが *https://api.example.com/apidocs/index.html* でホストされている場合、「試してみる」API呼び出しは *https://api.example.com* に転送されます。

FAQ

開発、テスト、本番など、複数のホストを指定できますか？

複数のホストはOpenAPI 3.0でサポートされています。2.0は、API仕様ごとに1つの`host`のみをサポートします（HTTPとHTTPSを異なるホストとしてカウントする場合は2つ）。複数のホストをターゲットにする1つの方法は、仕様から`host`と`schemes`を省略し、各ホストから提供することです。この場合、仕様の各コピーは対応するホストをターゲットにします。

ホストとbasePathはテンプレートをサポートしていますか？例えば

https://{customer_id}.saas-app.com/api/v1
https://api.saas-app.com/v1/{customer_id}/apis

これはOpenAPI 3.0でサポートされていますが、2.0ではサポートされていません。ホストテンプレートの回避策については、前の質問を参照してください。

HTTPとHTTPSで異なるポートを指定できますか？例えば

http://example.com:8080
https://example.com:8443

これはOpenAPI 3.0でサポートされていますが、2.0ではサポートされていません。2.0では、`host`と`schemes`を省略し、両方のホストから仕様を提供できます。このように、仕様の各コピーは、その仕様にアクセスするために使用されるホストとポートをターゲットにします。

リファレンス

host、basePath、schemesフィールド

お探しの情報が見つかりませんか？コミュニティに質問する
間違いを見つけましたか？お知らせください