在远程服务器上托管可重用组件定义，并在openapi规范3.0中将它们用作$ref

Question

我正在尝试在OAS 3.0(OpenAPI规范3.0(中创建可重用组件定义并通过$ref引用它们。我尝试了以下内容：

1. 在我的本地机器上下载了Swagger编辑器
2. 在我的本地机器上创建了一个文件，其中包含一个我们希望在多个API中重用的公共响应
3. 在规范中提供了该文件的参考-"$ref": "file:///path of local directory/myreference.json"

输出不反映我引用的文件的内容。我在这里做错什么了吗？

还想知道，如果假设我们在一些像GitHub这样的repo上托管这样的规范，那么它们会正确解析引用吗？它们能被一些CMS系统获取来呈现UI吗？

感谢在这个问题上的任何建议。

Answer 1

Hej Santosh，

OpenAPI不支持区域设置文件系统引用的绝对路径。来自swagger.io的文档您可以看到，在您的情况下，您想尝试远程引用方法位于另一个文件夹场景中的文档元素使用到您的规范位置的相对路径：

• 本地引用–$ref: '#/definitions/myElement'#表示转到当前文档的根目录，然后逐个查找元素定义和myElement
• 远程引用–$ref: 'document.json'使用位于同一服务器和同一位置的整个文档。
  • 位于同一服务器上的文档元素–$ref: 'document.json#/myElement'
  • 位于父文件夹中的文档元素–$ref: '../document.json#/myElement'
  • 位于另一个文件夹中的文档元素–$ref: '../another-folder/document.json#/myElement'
• URL参考–$ref: 'http://path/to/your/resource'使用位于不同服务器上的整个文档。
  • 存储在不同服务器上的文档的特定元素–$ref:'http://path/to/your/resource.json#myElement'使用相同协议(例如，HTTP或HTTPS(的不同服务器上的文档–$ref:'//anotherserver.com/files/example.json'

Answer 2

虽然$ref: file:///path是有效的JSON引用^[1]，但您不应该使用它们，因为它们不可移植。相反，使用相对参考文献，如$ref: '../relative/path/to/file.yaml'或类似文献，如lordrodos的回答中所建议的。

$ref: file:///...在Swagger UI和Swagger Editor中不起作用的原因是它们是网页，使用JavaScript解析定义，并且浏览器出于安全原因拒绝从JavaScript访问file:///方案

你能推荐一个可以用来托管可重复使用的定义文件的网站吗？

SwaggerHub为OpenAPI定义提供云托管。可重用组件(模式定义、响应等(可以存储在所谓的"；域"；文件，并在多个API定义中使用。

披露：我为SwaggerHub的制造公司工作

---

^[1] _{根据JSON参考规范：}

_{$ref"；字符串值包含一个URI[RFC3986]，}

_{和file:///...是有效的URI}