我目前正在使用Spring REST文档为我的RESTful服务生成文档,并且我希望生成一个表格,其中包含可能的响应状态值以及描述,例如它已完成here(在页面底部)。
我可以在我的父index.adoc
文件中手动执行此操作,其中包含已生成的文件,但我不喜欢它,因为它会使我的文档分散,尽管我希望将整个签名描述保留在单一的地方。
我已经阅读了REST Docs文档并在StackOverflow和项目的GitHub问题上进行了搜索,但是还没有看到任何提及此类功能。
我错过了什么,或者我正在寻找的功能没有实现,甚至不需要?
答案 0 :(得分:3)
您正在寻找的功能未实现,我认为不需要。
当您开发和记录RESTful API时,您应该尽可能使API在使用HTTP状态代码方面保持一致,并且您还应该使用每种状态的标准,易于理解的含义。如果您遵循这两个指导原则,您可以避免完全记录状态代码,也可以在概述部分记录一次。
您链接到的文档提供了一些我认为您不应该做的事情:
简而言之,非标准地使用HTTP状态代码意味着需要记录它们。如果非标准使用因资源而异,那么它也意味着需要为每种资源记录它们。
如果您避免犯了上述错误,您可以节省一些工作,同时让您的用户更轻松。