使用 Spring REST Docs 记录响应状态答案

【问题标题】：Document response status with Spring REST Docs使用 Spring REST Docs 记录响应状态
【发布时间】：2017-04-07 12:07:11
【问题描述】：

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

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

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

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

【问题讨论】：

【解决方案1】：

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

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

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

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

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

【讨论】：

感谢您的回复！听起来很合理。事实上，我提供的示例并不是 HTTP 状态使用的最佳案例。但是，我仍然略微不同意您关于该功能无用的问题。 HTTP 状态代码太多了，所以，在我看来，如果文档提供了客户应该知道的代码列表，那就太好了。这就是为什么我寻找这样的功能。无论如何，非常感谢您的意见。
如果 API 被阻止或无效，我更愿意使用 401，因为 401 的语义未经身份验证。 403 表示应用知道你是谁，但不允许你访问资源。
另外：我同意 HTML 响应代码的非标准使用是不正常的。不要这样做，它会混淆人们的地狱。