記錄REST路由和響應

Question

我正在用Scala後端和JS前端構建REST應用程序。這些路線直觀地被設計爲匹配邏輯，便利和可讀性。

但是：

1. 哪些記錄REST路線和響應主體格式標準的做法？
2. 是否有任何工具可以生成這樣的文檔？

Answer 1

您可以使用Swagger或IO-Docs

例如與揚鞭你有很多不同的集成工具，你可以用它來自動生成你的代碼（通常在其中添加一些元數據）。

使用此類工具時很酷的事情是，您將獲得免費的API資源管理器，作爲交互式文檔！

Answer 2

一些希望有用的提示。

1. 文檔這是用來做什麼的URL
2. 創建例如請求的HTTP方法（如果可能的話，這東西可以複製粘貼，並使用與API玩）
3. 文件可能被返回的所有HTTP響應（400 - 錯誤請求，500 - 服務器錯誤，201 - 確定，不返回內容，201 - 確定，創建等）
4. 澄清哪些HTTP代碼與某些錯誤消息（您的錯誤代碼，錯誤描述）相關聯
5. 記錄給定請求的響應如何，哪些字段總是返回這些都是可選的。

我不知道任何現成的工具來自動生成此類文檔。我見過使用額外標籤的自定義JavaDoc插件，例如

/** 
* Description... 
* 
*/ 
@Path("/") 
class RestResource{ 

/** 
    * @JsonRequest {...} 
    * @JsonResponse {...} 
    * @Http 400 - bad request 
    * @Http 201 - ok, resource created 
    * 
    */ 
    @Path("/restMethod") 
    public void restMethod() 
//... 
} 

這是以JavaDoc格式生成所需文檔。這也很容易拿出的東西，會產生維基文字等