使用Node/JS REST API提供文檔

Question

我正在使用Node和Express構建REST API，並且希望爲它提供文檔。我不想手工製作這個產品，並且似乎有Swagger，RAML和Api Blueprint/Apiary等形式的解決方案。

我真的很喜歡將文檔從API代碼中自動生成，儘可能使用Swashbuckle或微軟提供的解決方案，但是它們可以通過強大的打字和反射來實現。

對於JS世界來說，正確的選擇是使用Swagger/RAML/Api Blueprint標記來定義API，然後從中生成文檔和腳手架服務器。前者看似簡單，但我對後者不太確定。我所見過的所有這些選項的服務器代碼生成看起來都非常有限。需要有一些方法來將自動生成的代碼與手動代碼分開，以便可以輕鬆更新定義，並且我沒有看到任何跡象或討論。它似乎不是一個難以逾越的問題（我比.NET更熟悉.NET，所以我可能很容易遺漏某些東西），並且提到了這個問題以及解決方案正在從一年前的previous Stack Overflow question中得到解決。

任何人都可以告訴我，如果我失蹤/誤解任何東西，如果有解決上述問題的存在？

Answer 1

我對API和動態語言的使用經驗是重點在於驗證而不是代碼生成。例如，如果使用編譯語言，我會根據API規範生成構件並使用它來強制執行正確性。通過生成接口而不是具體類來支持圓跳閘。

使用動態語言，在測試時使用spec來保證所有定義的API都被測試覆蓋，並且響應符合規範（由於Postel定律，我傾向於不驗證請求，但它也是可能的）。

Answer 2

swagger-node-express的初始版本正是這樣做的 - 您可以從路由，模型等中定義一些元數據，並且文檔將自動從其生成。鑑於javascript是如何動態的，對於很多用戶來說，這變得有點麻煩，因爲它要求您保持元數據在某種程度上與模型保持最新的關係。

快進和最新的swagger-node項目採取了一種替代方法，在某種意義上可以認爲符合「從代碼生成文檔」。在這個項目中（對於java，swagger-inflector和python的connexion）採用swagger規範爲爲api的DSL，並且路由邏輯由swagger文檔中定義的內容處理。從那裏，你只需實現控制器。

如果您將swagger規範視爲「類似代碼」，那麼這是一種非常有效的方式 - 文檔可以從字面上永遠不會過時，因爲它用於構建所有路由，驗證所有輸入變量，並且將API連接到您的業務層。

雖然真正的代碼生成，比如什麼是可從swagger-codegen項目可以是非常有效的，它需要你的代碼一些巧妙融合後您最初構建服務器。以上三個項目的工作流程完全消除了這種考慮。

我希望這有幫助！