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 

但我不知道這是構建你的腎錯構瘤的好方法。