记录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格式生成所需文档。这也很容易拿出的东西，会产生维基文字等