使用Spring REST Docs记录响应状态

Question

我目前正在使用Spring REST文档为我的RESTful服务生成文档，并且我希望生成一个表格，其中包含可能的响应状态值以及描述，例如它已完成here（在页面底部）。

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

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

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

Answer 1

您正在寻找的功能未实现，我认为不需要。

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

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

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

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

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