Skip to content
This repository is currently being migrated. It's locked while the migration is in progress.

Latest commit

 

History

History
60 lines (38 loc) · 2.67 KB

cors.md

File metadata and controls

60 lines (38 loc) · 2.67 KB
Raw

CORS

CORS is a technique to prevent websites from doing bad things with your personal data. Most browsers + JavaScript toolkits not only support CORS but enforce it, which has implications for your API server which supports Swagger.

You can read about CORS here: http://www.w3.org/TR/cors.

There are two cases where no action is needed for CORS support:

  1. swagger-ui is hosted on the same server as the application itself (same host and port).
  2. The application is located behind a proxy that enables the required CORS headers. This may already be covered within your organization.

Otherwise, CORS support needs to be enabled for:

  1. Your Swagger docs. For Swagger 2.0 it's the swagger.json/swagger.yaml and any externally $refed docs.
  2. For the Try it now button to work, CORS needs to be enabled on your API endpoints as well.

Testing CORS Support

You can verify CORS support with one of three techniques:

  • Curl your API and inspect the headers. For instance:
$ curl -I "http://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

This tells us that the petstore resource listing supports OPTIONS, and the following headers: Content-Type, api_key, Authorization.

  • Try swagger-ui from your file system and look at the debug console. If CORS is not enabled, you'll see something like this:
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 cannot easily show this error state.

  • Using the http://www.test-cors.org website. Keep in mind this will show a successful result even if Access-Control-Allow-Headers is not available, which is still required for Swagger-UI to function properly.

Enabling CORS

The method of enabling CORS depends on the server and/or framework you use to host your application. http://enable-cors.org provides information on how to enable CORS in some common web servers.

Other servers/frameworks may provide you information on how to enable it specifically in their use case.

CORS and Header Parameters

Swagger lets you easily send headers as parameters to requests. The name of these headers MUST be supported in your CORS configuration as well. From our example above:

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

Only headers with these names will be allowed to be sent by Swagger-UI.