跳到内容

CORS

CORS 是一种防止网站滥用您的个人数据的技术。大多数浏览器和 JavaScript 工具包不仅支持 CORS，而且强制执行它，这对于支持 Swagger 的 API 服务器有影响。

您可以在此处阅读有关 CORS 的信息：http://www.w3.org/TR/cors。

在以下两种情况下，CORS 支持不需要任何操作

  1. Swagger UI 与应用程序本身托管在同一服务器上（相同主机和端口）。
  2. 应用程序位于启用所需 CORS 头的代理之后。这可能已在您的组织内部覆盖。

否则，CORS 支持需要为以下内容启用

  1. 您的 Swagger 文档。对于 Swagger 2.0，它是 swagger.json/swagger.yaml 以及任何外部 $ref 引用的文档。
  2. 为了使 立即尝试 按钮正常工作，您的 API 端点也需要启用 CORS。

测试 CORS 支持

您可以通过以下三种技术之一验证 CORS 支持

  • Curl 您的 API 并检查头部。例如
终端窗口
1
$ curl -I "https://petstore.swagger.io/v2/swagger.json"
2
HTTP/1.1 200 OK
3
Date: Sat, 31 Jan 2015 23:05:44 GMT
4
Access-Control-Allow-Origin: *
5
Access-Control-Allow-Methods: GET, POST, DELETE, PUT, PATCH, OPTIONS
6
Access-Control-Allow-Headers: Content-Type, api_key, Authorization
7
Content-Type: application/json
8
Content-Length: 0

这告诉我们 petstore 资源列表支持 OPTIONS，以及以下头部：Content-Type、api_key、Authorization。

  • 从您的文件系统尝试 Swagger UI 并查看调试控制台。如果未启用 CORS，您会看到类似这样的内容
1
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 网站验证 CORS 支持。请记住，即使 Access-Control-Allow-Headers 不可用，此网站也会显示成功结果，但 Swagger UI 正常运行仍然需要它。

启用 CORS

启用 CORS 的方法取决于您用于托管应用程序的服务器和/或框架。https://enable-cors.org 提供了如何在一些常见 Web 服务器中启用 CORS 的信息。

其他服务器/框架可能会提供关于如何在其特定用例中启用它的信息。

CORS 和头部参数

Swagger UI 允许您轻松地将头部作为参数发送到请求。这些头部的名称也必须在您的 CORS 配置中受支持。从我们上面的示例来看

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

Swagger UI 只允许发送具有这些名称的头部。

© . All rights reserved.