使用Spring REST文档回复文档的状态

Question

我正在使用Spring REST Docs为我的REST风格的服务生成文档，并且我想生成一个可能的带有说明的响应状态值表，如here（在底部的页面）。

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

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

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

Answer 1

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

当您正在开发和编写RESTful API时，应该尽可能使您的API尽可能一致地使用HTTP状态代码，并且还应该使用标准的，每种状态的理解含义。如果遵循这两条准则，则可以避免完全记录状态代码，也可以在概览部分中记录一次。

你链接到提供什么，我不认为你应该做的几个例子的文档：

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

总之，使得不规范使用的HTTP状态代码意味着他们需要记录。如果非标准使用因资源而异，那么这也意味着它们需要记录在每个资源中。

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