api.raml 应该包含整个 API 吗？

Question

我有一个关于 RAML（RESTful Api 建模语言）的简单问题。我想尝试一些新的东西，以便为我的 API 创建文档（并稍后对其进行测试）。 API写成node.js.

我应该将我的全部代码包含在 api.raml 文件中吗？或者是否可以从其他 .raml 文件导入子路由？有什么好的指导方针来划分 .raml 文件吗？

例如我想创建一个名为 books.raml 的文件。它将包括 /books 下的所有路线。然后我想把它导入我的api.raml，这样它就更像是一个只包含子文件的文件。

可以吗？如果是，我该怎么做？关于将这些文件存储在何处（在哪个目录中）的准则是什么？

Answer 1

您可以将 RAML 规范分成几个文件，并使用 !include 指令来包含文件。

例如：

#%RAML 1.0
title: My API with Types
types: !include myTypes.raml

更多信息包括 here

除此之外，RAML 还提供库："RAML libraries are used to combine any collection of data type declarations, resource type declarations, trait declarations, and security scheme declarations into modular, externalized, reusable groups"

使用什么以及如何使用取决于您的用例。但我认为图书馆可以提供更好/更有意义的结构。

查看有关 modularization 的部分了解更多信息。

您还可以像您所说的那样包含路线，例如：

#%RAML 1.0
title: bla
/foo/:
  /bar/:
    post:
    get:
/books: !include books.raml

但我不确定这是构建 RAML 的好方法。

api.raml 应该包含整个 API 吗？

Should api.raml contain the whole API?

rest

api-design

node.js

raml