什么是生成REST API文档的最佳方式？
我正在寻找一个很好的方式来为REST API生成文档。它不需要实际与代码或任何其他东西连接，但能够将文档编写为文本文件，将工具指向它并从中生成一些文档是非常棒的。什么是生成REST API文档的最佳方式？
有没有人有任何想法？我知道我有点含糊，但说实话，我不太清楚我在这里寻找什么 - 主要是一种管理文档的简单方法。
"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的好处之一。
我认为关键的一点是，确实没有记录媒体类型的标准化方式。如果只有那里。它当然不能生成。 – 2010-10-14 23:37:46
虽然不是REST，但我使用Sphinx来记录由API参考和教程组成的XML-RPC API。 Sphinx为ReStructuredText添加了一些方便的指令，以获得您要求的几乎所有内容：Sphinx转换为HTML和PDF的ReStructuredText格式化文本文件集合，包含索引和目录。狮身人面像易于使用和记录良好;我认为说你可以在大约十分钟内开始使用它并不夸张。
一些RESTful系统实际上能够编写自己的API。看看RESTx，它可以做到这一点：您编写组件，然后通过向服务器发送这些组件的参数（无论是JSON还是通过Web表单）来创建新的Web服务。然后你得到这些参数的URI。访问它将调用带有参数的组件并检索结果。
无论如何，组件以及创建的RESTful Web服务都会获得自动生成的文档，这些文档是可浏览的，可以通过HTML或JSON格式进行检索。
为什么你需要一个文档文件来生成文档？我的意思是，实际上，你为什么不直接在Open Office中编写文档或将其保存为PDF，XML等？其他工具，如doxygen，是为了从源代码和评论中产生文档。 – 2010-10-14 20:05:47
对不起，应该提到 - 我想从中生成HTML文件，但我宁愿不编辑HTML来生成它。我真的只是寻找一种方法来将文档保存为格式最小的格式（使用Markdown或类似的格式），然后将其转换为一堆链接的HTML文件。 – 2010-10-14 20:07:56