Apicurio-studio: 支持跨规范文档引用组件对象

用例

这将解决的主要用例是让用户能够集中他们的数据类型定义，可能在单个文件（或一组文件）中。 然后可以通过引用它们的中心位置在多个 API 定义中利用这些数据类型。

注意事项

为了支持外部引用，需要进行一些增强。 这是一个没有特定顺序的列表：

• 必须增强数据模型库（当前oai-ts-core但很快将成为apicurio-data-models ）以支持可插入的引用解析器。 目前这些库只能解析内部引用。 相反，库的使用者必须能够提供自定义引用解析器，以便可以成功解析外部引用。

• Apicurio Studio 应该支持“仅数据类型”样式资源，并带有一个专注于设计数据类型的编辑器。 这允许更具体的工作流程来创建/管理独立于 API 设计的数据类型。

• 在 API 设计编辑器中设置类型时，工具需要一种从外部资源中选择类型的方法。 我们需要考虑如何最好地将这些外部类型显示给用户以供选择。 可能我们需要一种 API 设计“导入”其他资源/文件的方法，以便 UI 可以缩小用户的选择范围并合理地显示它们。 请记住，编辑器需要获取和解析任何外部资源，以便在某种选择 UI 控件中显示它们的可用数据类型。

• 我们可能需要决定是否可以将正在进行的数据类型资源用作 API 设计中外部引用的来源。 换句话说，是否可以在 API 设计中引用“快照”数据类型？ 或者我们是否应该要求数据类型资源是“最终的”，然后才能用作外部引用的来源。 如果是前者，那么我们不能“最终确定”一个 API 设计，直到它的依赖关系也最终确定。 注意：整个概念需要我们在 Apicurio 中实现最终资源！

• 在引用 Apicurio 资源时，我们需要决定 $ref 格式是什么。 目前，任何 API 设计（或理论上的数据类型资源）都有唯一的 ID，但它是在创建时生成的不透明 ID。 目前，该 ID 是唯一标识资源以用于解析目的的唯一方法。 一旦资源最终确定（如果我们支持这样的概念），那么我们也许可以授予资源一个更人性化的标识符，然后在 $ref URI 中使用它。 无论我们做什么，都应该注意，当将资源发布到 API 注册表（另一个未来功能）时，API 设计中的任何 $references 都需要由 API 注册表以某种合理的方式解析。

以下是有关$ref允许值的一些信息：

即使 $ref 的值是一个 URI，它也不是一个网络定位器，只是一个标识符。 这意味着架构不需要在该 URI 上可访问，但它可能是。 如何处理外部模式 URI 基本上取决于验证器实现，但不应假设验证器将获取 $ref 值中指示的网络资源。

有关参考的更多信息可以在OpenAPI 规范和JSON 参考 RFC 中找到。

是否可以优先考虑从 Apicurio 中的另一个规范（而不是最初的外部引用）对 DataTypes 的引用的实现？

我这么说的原因是，对于 Swagger 的任何重要使用，一些交叉引用功能都是必要的。 例如，我们正在实施各种共享数据类型（例如地址、人员等）的服务，并希望将 Apicurio 用于所有这些的规范。 但是，目前我们不能，因为无法使用交叉引用。

是否可以优先考虑从 Apicurio 中的另一个规范（而不是最初的外部引用）对 DataTypes 的引用的实现？

我这么说的原因是，对于 Swagger 的任何重要使用，一些交叉引用功能都是必要的。 例如，我们正在实施各种共享数据类型（例如地址、人员等）的服务，并希望将 Apicurio 用于所有这些的规范。 但是，目前我们不能，因为无法使用交叉引用。

同意，这将使我们进入杀手级应用领域。

@jsenko看起来，一旦我们完成了注册表 impl，我们就有了来自社区的明确优先级。 :)

我很乐意看到这一点，在工作中使用 apicurio 和参考资料对不同的团队非常有用。

我意识到这花了一点时间，但是从 Beta 2.46 开始正式支持外部引用，这是下一个版本（希望明天完成）。 有一个新的 UI 可以将其他 Apicurio Studio 文档中的数据类型和响应导入到当前文档中。 此外，验证已更新以支持解析外部 http/s 以及 Apicurio 内部引用。 这应该是迈向成熟支持跨文档引用的良好的第一步。