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

Question

我目前正在使用 Spring REST Docs 为我的 RESTful 服务生成文档，并且我想生成一个带有描述的响应状态的可能值表，就像在这里完成的一样（在页面底部）。

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

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

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

Answer 1

您正在寻找的功能没有实现，在我看来，它不是必需的。

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

您链接到的文档提供了一些我认为您不应该做的示例：

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

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

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