时间戳

首页 > 解决方案 > REST 文档是否必须包含每个请求参数的所有可能值？

java - REST 文档是否必须包含每个请求参数的所有可能值？

问题描述

在编写 REST doc 文档时，是否可以编写每个请求参数的所有可能值？我认为这更好，即使有许多其他方法可以获取源代码等信息。但我不确定。有正确的答案，还是只是团队政策的问题？

标签： javaspringrestdocumentation

解决方案

我认为这个问题的答案取决于你正在从事的项目。如果这个 API 将被许多其他开发人员使用并向所有人开放，我认为最好使用不同的语言放置一些示例代码片段，并解释每个参数，例如用于什么以及应该考虑的限制。我认为您不需要在简单地解释每个参数本身之后放置所有可能的组合。您可以查看流行的项目 API 文档来了解一下；例如 ：

Github API 文档

Twitter API 文档

Dropbox API 文档

这些文档提供了开发人员需要的每一个细节。如果此 API 仅适用于您的小团队，并且您不需要如此详细的解释，您可以使用类似 Swagger 的工具来轻松记录您的 API。

昂首阔步

推荐阅读