CORS

CORS は、Web サイトが個人データを使用して不正なことを行うのを防ぐための手法です。ほとんどのブラウザと JavaScript ツールキットは CORS をサポートするだけでなく、強制します。これは、Swagger をサポートする API サーバーに影響します。

CORS についてはこちらをご覧ください: http://www.w3.org/TR/cors.

CORS サポートのために何もする必要がない場合は 2 つあります

  1. Swagger UI がアプリケーション自体と同じサーバー（同じホスト*と*ポート）でホストされている場合。
  2. アプリケーションが、必要な CORS ヘッダーを有効にするプロキシの背後にある場合。これは、組織内で既にカバーされている可能性があります。

それ以外の場合は、CORS サポートを有効にする必要があります

  1. Swagger ドキュメントの場合。Swagger 2.0 の場合は、swagger.json/swagger.yaml と、外部で $ref されたドキュメントです。
  2. 今すぐ試すボタンを機能させるには、API エンドポイントでも CORS を有効にする必要があります。

CORS サポートのテスト

CORS サポートは、次の 3 つの方法のいずれかで確認できます

  • API を Curl し、ヘッダーを検査します。例えば
$ curl -I "https://petstore.swagger.io/v2/swagger.json"
HTTP/1.1 200 OK
Date: Sat, 31 Jan 2015 23:05:44 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, PUT, PATCH, OPTIONS
Access-Control-Allow-Headers: Content-Type, api_key, Authorization
Content-Type: application/json
Content-Length: 0

これは、petstore リソースリストが OPTIONS と次のヘッダーをサポートしていることを示しています: Content-Type、api_key、Authorization.

  • ファイルシステムから Swagger UI を試して、デバッグコンソールを確認します。CORS が有効になっていない場合は、次のようなメッセージが表示されます
XMLHttpRequest cannot load http://sad.server.com/v2/api-docs. No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'null' is therefore not allowed access.

Swagger UI はこのエラー状態を簡単に表示できません。

  • https://www.test-cors.org Web サイトを使用して、CORS サポートを確認します。Access-Control-Allow-Headers が利用できない場合でも、正常な結果が表示されることに注意してください。これは、Swagger UI が正常に機能するために依然として必要です。

CORS の有効化

CORS を有効にする方法は、アプリケーションをホストするために使用するサーバーまたはフレームワークによって異なります。https://enable-cors.org は、一般的な Web サーバーで CORS を有効にする方法に関する情報を提供しています。

他のサーバー/フレームワークは、ユースケースで具体的に有効にする方法に関する情報を提供する場合があります。

CORS とヘッダーパラメーター

Swagger UI を使用すると、ヘッダーをパラメーターとしてリクエストに簡単に送信できます。これらのヘッダーの名前は、CORS 構成でもサポートされている*必要*があります。上記の例から

Access-Control-Allow-Headers: Content-Type, api_key, Authorization

これらの名前のヘッダーのみが Swagger UI によって送信されることが許可されます。