使用Spring REST Docs记录响应状态

时间:2017-04-07 12:07:11

标签: spring-restdocs

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

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

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

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

1 个答案:

答案 0 :(得分:3)

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

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

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

  1. 它记录了200表示请求成功。这是200响应的标准含义,因此文档添加很少
  2. 402用于​​被阻止的API密钥,但它实际上意味着需要付款。 403(禁止)响应可能更合适
  3. 它滥用404(未找到)表示已超出速率限制
  4. 简而言之,非标准地使用HTTP状态代码意味着需要记录它们。如果非标准使用因资源而异,那么它也意味着需要为每种资源记录它们。

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