通过代码注释生成API文档。

Question

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

- hellopat

Answer 1

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

我不熟悉任何类似于Node.js的工具（例如使用Express.js DSL）。

当编写生成蓝图的工具时，可以避免手动撰写蓝图，而改用 Matter Compiler。此工具（Ruby gem）将JSON或内存树（AST）转换为API Blueprint。

请注意，我个人建议不要从代码中生成文档。相反，我认为API Blueprint是可以用来测试API实现的合同。

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

- Zdenek

---

能否使用API蓝图为Java语言通过代码注释生成API文档？ - moh

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

- Srikanth Hugar