コンテンツにスキップ

API ホストとベースパス

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

1
host: petstore.swagger.io
2
basePath: /v2
3
schemes:
4
    - https

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

URL structure

schemes

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

1
schemes:
2
    - http
3
    - https

または配列リテラル構文

1
schemes: [http, https]

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

host

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

ターミナルウィンドウ
1
api.example.com
2
example.com:8089
3
93.184.216.34
4
93.184.216.34:8089

不正な例

ターミナルウィンドウ
1
http://api.example.com
2
example.com/api/v1

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

basePath

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

ターミナルウィンドウ
1
/v2
2
/api/v2
3
/

不正な例

ターミナルウィンドウ
1
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つ）。複数のホストを対象とする可能な方法は、仕様からhostとschemesを省略し、各ホストから提供することです。この場合、仕様の各コピーは対応するホストを対象とします。

hostとbasePathはテンプレートをサポートしていますか？例えば
ターミナルウィンドウ
1
https://{customer_id}.saas-app.com/api/v1
2
https://api.saas-app.com/v1/{customer_id}/apis

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

HTTPとHTTPSで異なるポートを指定できますか？例えば
ターミナルウィンドウ
1
http://example.com:8080
2
https://example.com:8443

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

参照

host、basePath、およびschemesフィールド

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