通过代码注释生成API文档

Question

我正在使用aglio生成我的API文档。我目前正在根据规范编写原始标记。我想知道是否有一种方法可以通过代码中的注释直接生成减价。有人知道怎么做吗？

Answer 1

从技术上讲，这是可能的。取决于您的语言和使用的框架。例如，在Ruby中，可以使用RSpec生成。

我不熟悉为Node.js做类似事情的任何工具(例如使用Express.js DSL)。

在编写生成蓝图的工具时，可以避免手工编写蓝图，而是使用物质编译器。这个工具(Ruby )将JSON或内存树(AST)转换为。

请注意，我个人建议不要从代码中生成文档。相反，我认为API是一个可以用于测试您的API实现的契约。

从这个意义上说，从代码生成蓝图就像从代码生成测试(测试相同的代码)。

Answer 2

我不知道agilo，但其他替代解决方案是使用maven站点插件生成API文档。

 <plugin>
    <artifactId>maven-site-plugin</artifactId>
    <groupId>org.apache.maven.plugins</groupId>
    <version>${maven-site-plugin.version}</version>
    <configuration>
      <locales>en,fr</locales>
    </configuration>
  </plugin>

您可以编写包含API细节的apt文件，然后可以运行maven来生成文档。这就产生了一个好医生。这是非常流行和许多人在工业中广泛使用。

关于http://maven.apache.org/plugins/maven-site-plugin/examples/creating-content.html的更多细节