node.js - 通过代码注释生成 API 文档

Question

我正在使用 aglio 来生成我的 API 文档。我目前正在根据 API Blueprint 规范为此编写原始降价。我想知道是否有办法直接在代码中通过注释生成降价。有人知道这样做的方法吗？

Answer 1

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

我不熟悉任何对 Node.js 执行类似操作的工具（例如使用 Express.js DSL）。

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

请注意，我个人建议不要从代码生成文档。相反，我将 API 蓝图视为可用于测试您的 API 实现的合同。

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

Answer 2

我不知道敏捷，但其他替代解决方案是使用 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 来生成 doc。它生成了不错的文档。这是非常受欢迎的，许多业内人士广泛使用。

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