spring-restdocs - 使用 Spring REST Docs 记录响应状态

Question

我目前正在使用 Spring REST Docs 为我的 RESTful 服务生成文档，我想生成一个包含响应状态可能值和描述的表，就像完成了一样 here (在页面底部)。

我可以在我的父 index.adoc 文件中手动执行此操作，其中包括生成的文件，但我不喜欢它，因为它使我的文档散乱，尽管我想保留整个签名描述在一个地方。

我已经阅读了 REST Docs 文档并在 StackOverflow 和项目的 GitHub 问题上进行了搜索，但没有看到任何提及此类功能的内容。

我是不是遗漏了什么，或者我正在寻找的功能没有实现，甚至不需要？

Answer 1

您正在寻找的功能未实现，在我看来，它不需要。

当您开发和记录 RESTful API 时，您应该尝试使您的 API 在使用 HTTP 状态代码的方式上尽可能保持一致，并且您还应该使用每个状态的标准、易于理解的含义。如果您遵循这两条准则，您可以完全避免记录状态代码，或者您可以在概述部分中记录一次。

您链接到的文档提供了一些我认为您不应该做的事情的例子:

1. 它记录了 200 表示请求成功。这是 200 响应的标准含义，因此文档添加的内容很少
2. 402 用于被阻止的 API key ，但它实际上意味着需要付款。 403(禁止)响应可能更合适
3. 它滥用 404(未找到)来指示已超过速率限制

简而言之，以非标准方式使用 HTTP 状态代码意味着需要对它们进行记录。如果非标准使用因资源而异，那么这也意味着需要为每个资源记录它们。

如果您避免犯上述错误，您可以节省一些工作，同时让您的用户更轻松。