从单元测试生成 REST-API 文档答案

【问题标题】：REST-API documentation generation from unittests从单元测试生成 REST-API 文档
【发布时间】：2016-02-26 10:06:29
【问题描述】：

我想自动记录我的 REST-API。我知道，有很多工具可以做到这一点，但我想从我的单元测试中生成文档。

这样做的原因是，我希望文档能够反映，什么是测试的，什么不是。尽管如此，文档应该和swagger 生成的文档一样丰富。

我已经找到了两个采用这种方法的项目，doctester 和 testdoc4j。两者都不能满足我的需要。生成的文档不会汇总快乐路径和错误路径。

你使用什么工具，你能推荐一个好的吗？

干杯。

编辑：

记录在接口中定义的 API 合同与记录测试场景是有区别的。如果我的文档只包含经过测试的端点和路径，我可以定义我的接口并且只能分发我测试过的部分。

这意味着我可以定义一个带有十个端点的接口。在用相应的测试实现一个基本功能后，我可以用文档发布这部分。尚未包含尚未稳定或已实现的端点，这会阻止用户使用它们。

【问题讨论】：

【解决方案1】：

也许您想要一个BDD 框架？例如：

【讨论】：

【解决方案2】：

我最近对同一主题进行了一些研究，并决定使用免费版本的Miredot，因为它是唯一满足我要求的工具：

当您运行mvn test 时，Miredot 会自动生成基于 HTML 的文档

【讨论】：

你是对的，文档是在测试步骤中生成的，但它指的是合同定义而不是测试。
Miredotter 在这里.. 只是为了确认。 Miredot 在编译步骤之后挂钩到 maven 生命周期。运行 mvn test 可确保 Miredot 也运行。我们只关注代码、注释和 Javadoc，而不是测试。

【解决方案3】：

Swagger 是一个不错的选择。这是 GitHub 上的一个项目，具有 Maven 集成和许多其他选项以保持其灵活性。

更多信息：here

【讨论】：

你是对的，swagger 生成了一个结构良好的文档，但它不是来自测试。它将接口作为文档的来源，这是一个很大的区别。 Swagger 记录合同，而我想要实际测试用例的文档。