在远程服务器上托管可重用的组件定义，并在 open api spec 3.0 中将它们用作 $ref

Posted 2023-02-19

【中文标题】在远程服务器上托管可重用的组件定义，并在 open api spec 3.0 中将它们用作 $ref

【英文标题】：Hosting reusable component definitions on remote server and use them as $ref in open api spec 3.0

【发布时间】：2018-12-28 18:06:12

【问题描述】：

我正在尝试在 OAS 3.0（OpenAPI 规范 3.0）中创建可重用组件定义并通过 $ref 引用它们进行 POC。我在下面尝试过：

在我的本地计算机上下载了 Swagger 编辑器。 在我的本地计算机上创建了一个文件，其中包含我们希望跨多个 API 重复使用的公共响应。 在规范中给出了该文件的引用 - "$ref": "file:///path of local directory/myreference.json"

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

还想知道，如果我们在 GitHub 等存储库上托管此类规范，那么它们是否会正确解析引用，以及它们是否可以被某些 CMS 系统获取以呈现 UI？

感谢有关此问题的任何指示。

【问题讨论】：

浏览器控制台有错误吗？

嗨 Helen，控制台上没有错误，但它没有反映编辑器中的输出。

【参考方案1】：

虽然$ref: file:///path 是有效的 JSON 引用^[1]，但您不应使用它们，因为它们不可移植。相反，请使用 $ref: '../relative/path/to/file.yaml' 或类似的相对引用，如 lordrhodos's answer 中所建议的那样。

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

您能否推荐一个可用于托管可重用定义文件的站点？

SwaggerHub 为 OpenAPI 定义提供云托管。可重用组件（架构定义、响应等）可以存储在所谓的“域”文件中，并在多个 API 定义中使用。

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

---

^[1]_{根据JSON Reference Specification：}

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

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

【参考方案2】：

海吉·桑托什，

OpenAPI 不支持语言环境文件系统引用的绝对路径。来自documention over at swagger.io 您可以看到，在您的情况下，您想尝试使用 Remote Reference 方法来处理 位于另一个文件夹中的文档元素 场景，使用到您的规范位置的相对路径：

本地参考 - $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'

【讨论】：

嗨@lordrhodos，谢谢您的回复。您能否推荐一个可用于托管可重用定义文件的站点？

您可以使用任何公开的托管服务提供商或重新使用您“拥有”的任何域来托管文件。我建议您使用speccy 来验证您的规范。您还将获得基于 ReDoc 的精美文档预览。