创建高质量rest文档的免费工具/框架/程序？

Question

您能推荐免费的工具/框架/程序来创建高质量的rest文档吗？

谢谢

Answer 1

记录API的最佳位置通常在实现该API的代码中--文档最有可能与实现保持同步。这通常是通过一些特定格式的注释来完成的。

有许多工具可以从代码中提取文档(取决于实现语言)，但我个人最喜欢的工具是：

1. 狮身人面像 --这是一个基于python的工具链，带有"域“&其他几种编程语言的扩展，可以将ReStructuredText和MarkDown文件与从API源代码中提取的信息结合起来，生成许多输出格式的优秀文档。它与ReadTheDocs和GitHub兼容，可以自动(重新)生成文档。具体来说，有一个命令行api-doctool，鸦胆子素扩展为java提供了一个javasphix。
2. DoxyGen --从源代码生成文档的经典工具。

这两种工具是：

• 免费和开放源码
• 多平台( run是OS/X、Linux和Windows，而Sphinx将在python可以运行的任何地方运行)。
• 可以生成多种输出格式，包括HTML、手册页、纯文本和LaTeX，用于生成pdf。再加上其他人。
• 可以包含在构建过程中，以自动重新生成每个或特定版本上的文档。
• 可生成结构化、交叉链接、可搜索的文档，包括图表等。
• 提供自定义输出外观的机制-- 含氧通过自定义html、css & xml文件和狮身人面像(通过模板和自定义生成器)。
• 但是，在默认情况下，狮身人面像会产生更现代的文档。