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

除此之外肾错构瘤提供了图书馆：“肾错构瘤库用于数据类型声明，资源类型声明，特性声明的任何集合结合起来，和安全方案声明转化为模块化，外部化，可重复使用的组“

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

查看关于modularization的章节了解更多信息。

你也可以加入你的路由说，例如：

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

但我不知道这是构建你的肾错构瘤的好方法。