From 4bf3b209be1ae7725eebc037262be475feedc4d7 Mon Sep 17 00:00:00 2001 From: Kyle Shockey Date: Mon, 4 Dec 2017 21:24:14 -0800 Subject: [PATCH] Move CORS documentation --- README.md | 60 ---------------------------------------------- docs/usage/cors.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+), 60 deletions(-) create mode 100644 docs/usage/cors.md diff --git a/README.md b/README.md index 9693ae52..e74445c4 100644 --- a/README.md +++ b/README.md @@ -170,66 +170,6 @@ There are three options of passing config: These options can be used altogether, the order of inheritance is following (from the lowest priority to the highest): `swagger-config.yaml` -> config passed to `SwaggerUIBundle` -> config fetched from `configUrl` passed to `SwaggerUIBundle` -> config fetched from URL passed as a query parameter `config` -## CORS Support - -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 `$ref`ed 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: - -```bash -$ 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. ## Security contact diff --git a/docs/usage/cors.md b/docs/usage/cors.md new file mode 100644 index 00000000..f2d39709 --- /dev/null +++ b/docs/usage/cors.md @@ -0,0 +1,60 @@ +## CORS Support + +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 `$ref`ed 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: + +```bash +$ 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.