RAML- !include 奇怪的行为

Question

我使用 Atom 的 this 扩展来设计我的 API，用 RAML 编写。

我想我这里有问题:(我屏蔽了 title 和 baseUri，抱歉）:

如果我遵循 RAML 1.0 规范，我应该放一个“!include”。奇怪的是，apiworkbench 没有检测到错误。

如果我这样做：

为什么这不起作用？

Answer 1

不，对于库，您不能使用 include 关键字。

似乎规范对此不是很清楚，或者至少我找不到任何地方明确说明。因此提出一个问题是个好主意。

但是如果您查看规范中的 examples，您会发现在使用库时（使用 "uses" 关键字）省略了“!include”。

Answer 2

非常好的对话。事实上，规范应该更清楚地说明这一点，但是库采用与正常 !include 不同的方法的原因是，包含只是将新节点添加到您使用过 !include 关键字的现有节点。由于它确实是一个简单的 "add" 操作，因此它不会掩盖任何循环依赖性。

库有很大不同，命名空间 (uses) 的使用也有很大不同。库的目的是创建一组可共享的 assets/definitions 最佳实践，人们也可以使用这些最佳实践来创建自己的库或其他定义。循环依赖是不可避免的。为此，RAML 工作组必须想出一个不同于 !include 的机制。因此，对于库，您应该始终使用：

uses
  lib: mylib.raml

希望这解释了其背后的合理性，但如果您有更多问题，请告诉我。