无法加载外部 API 定义

Question

我们正在使用 SwaggerEditor 编写 OAS3 API 规范。现在我们希望采用更有条理的设置，将经常使用的通用定义（例如，一些参数、错误、对象类型）移动到一些共享文件以供其他 API 引用。

OAS3 使用普通的$ref 关键字支持这一点，例如：

$ref: "http://example.com/shared.yaml#/components/schemas/Person"

到目前为止我们尝试了什么

• 我们使用绝对 URL，即不是相对路径。

• 我们使用指向我们的规范文件的 url= 查询参数启动 SwaggerEditor。

  --> 共享 API 文件的指定 URL 显示在服务 API 标题下方的编辑器（右侧）的 Swagger UI 部分中，所以这似乎有效。

• 我尝试使用的引用是指向 YAML 文件的绝对 URL，我将其托管在与 swagger 编辑器相同的机器上（在 Apache Tomcat 中）。例如：

  $ref: "http://127.0.0.1:8080/foo/bar.yaml#/components/schemas/Person"

我设法在没有 CORS 错误的情况下启动了 SwaggerEditor（这在谷歌搜索此问题时似乎很常见，而且我们首先也发生过）。我可以在浏览器控制台中验证：

• 外部 YAML 文件实际上是使用所需的 CORS 标头 (Access-Control-... *) 发送的
• 浏览器控制台中没有其他错误。

但外部引用仍未解决：编辑器实际上并不检查给定的定义（在上面的示例中Person）是否存在 - 所以如果我引用了一些虚假的词，没有显示错误。此外，右侧的交互式 Swagger UI 部分也没有正确显示链接类型......即它不能正常工作。

不是 CORS 问题

（起初我们也遇到过这个问题，但现在按照以下步骤解决了。）

• 我确保为共享 YAML（上面的bar.yaml）设置了相应的 CORS 标头，即在 Apache Tomcat 的 web.xml 上设置过滤器。我验证了对 YAML 文件的请求获取了 CORS 标头 - 我正在获取...

  Access-Control-Allow-Origin *

• 打开 SwaggerEditor 时，请确保先清除浏览器缓存，因为浏览器可能仍然缓存了对引用的外部 YAML 文件的请求，因此会记住丢失的 CORS 标头。这可能会导致 SwaggerEditor 显示 CORS 错误¹，即使同时在服务器上使用正确的标头提供引用的资源。有关错误的更多详细信息也可以在浏览器开发控制台中找到²。

• 清除缓存后，我的 SwaggerEditor 再次正确加载文件，看到 CORS 标头并停止抛出 CORS 错误。

---

¹ 这是editor.swagger.io显示的错误：

错误

获取错误
获取http://127.0.0.1:8080/foo/bar.yaml失败

获取错误
可能的跨域 (CORS) 问题？ URL 来源 (http://127.0.0.1:8080) 与页面 (http://editor.swagger.io) 不匹配。检查服务器返回正确的 'Access-Control-Allow-*' 标头。

² 尝试使用外部引用加载 API 时浏览器 JS 控制台显示的错误：

CORS 策略已阻止从源“http://editor.swagger.io”获取“http://127.0.0.1:8080/foo/bar.yaml”的访问权限：请求的资源上不存在“Access-Control-Allow-Origin”标头。如果不透明的响应满足您的需求，请将请求的模式设置为“no-cors”以获取禁用 CORS 的资源。

Answer 1

我终于能够解决我们的问题。我们在调用 SwaggerEditor 时似乎使用了错误的查询参数。

要正确加载（和解析）外部 YAML 规范，应使用查询参数 configUrl（而不是 url！）。例如：

http://127.0.0.1:8080/swagger-editor-master/?configUrl=http://127.0.0.1:8080/foo/bar.yaml

在哪里...

• http://127.0.0.1:8080/swagger-editor-master/ 指向 Swagger 编辑器，并且
• http://127.0.0.1:8080/foo/bar.yaml 指向我们想要从我们当前在 Swagger 编辑器中编辑的任何内容中引用的规范文件。

像这样使用外部规范的引用，例如

$ref: "http://127.0.0.1:8080/foo/bar.yaml#/components/schemas/Payment"

将在右侧的 Swagger UI 中正确解析（例如，在 Schemas 部分中，引用的属性是可扩展的，等等）。但是，如果给出了无效的外部引用，编辑器似乎不会抛出错误（相反，Swagger UI 只显示一个“空”对象）。