生成REST API文档的最佳方法是什么？

Question

我正在寻找一种为REST API生成文档的好方法。它不需要实际连接代码或任何东西，但能够将文档编写为文本文件，将工具指向它并从中生成一些文档真是太棒了。

那里有人有什么想法吗？我知道我有点模糊，但说实话，我不太清楚我在这里寻找什么 - 主要是管理文档的简单方法。

Answer 1

According to Roy：

"A REST API should spend almost all of its descriptive
 effort in defining the media type(s) used for representing
 resources and driving application state, or in defining
 extended relation names and/or hypertext-enabled mark-up
 for existing standard media types."

自我描述性是REST的好处之一。

Answer 2

虽然不是REST，但我使用Sphinx来记录由API参考和教程组成的XML-RPC API。 Sphinx为ReStructuredText添加了一些方便的指令，以获得您所要求的内容：Sphinx转换为HTML和PDF的ReStructuredText格式文本文件的集合，包含索引和目录。 Sphinx易于使用且记录良好;我认为你可以在大约十分钟内开始使用它并不夸张。

Answer 3

有些RESTful系统实际上可以编写自己的API。看看RESTx，它就是这样做的：编写组件然后通过将这些组件的参数发送到服务器（作为JSON或通过Web表单）来创建新的Web服务。然后，您将获取这些参数的URI。访问它会使用参数调用组件并检索结果。

无论如何，组件以及创建的RESTful Web服务都会获得一个自动生成的文档，该文档是可浏览的，可以用HTML或JSON格式检索。