Question

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

Answer 1

技术上有可能。取决于您的语言和使用的框架。例如，在Ruby中，可以使用RSpec to generate API Blueprint。

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

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

请注意，我个人建议不要从代码中生成文档。相反，我认为API Blueprint是一个可以用于test your API implementation的合同。

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

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

的更多详情

通过代码注释生成API文档

2 个答案: