类似Javadoc的工具用于Spring-MVC REST API文档化？

Question

我正在寻找一种类似于Javadoc的REST API文档工具。我已经在javadoc中记录了我的rest控制器，我认为仅从中创建一个api文档给前端开发人员会很好。

我认为目前还没有这样的工具。有人有想法如何完成这个任务吗？我考虑使用经典的javadoc工具并添加一些spring/rest特定的逻辑。但我还不确定是否需要一些特殊的标记或可能会遇到什么问题。最终，我希望拥有一些可以集成到maven站点生命周期中的工具，但这应该不难实现。

处理继承可能会很困难：我在REST资源中经常使用它，但对于读者来说，继承关系是无关紧要的。因此，子控制器必须以某种方式集成超级控制器方法，但也能够在实际控制器的上下文中创建一些有意义的文档。我不确定spring是否允许我覆盖超级控制器中的方法，但仍然评估其注释。

我希望得到任何与相关项目、已存在的工具或只是您使用javadoc工具的经验方面的提示！

- Jan

Answer 1

你应该看一下RESTdoclet。 http://ig-group.github.com/RESTdoclet/

- Robert Morschel

---

他们在HP上提到：“Java 5/6支持。Java 7即将推出”，因此他们在某种程度上停止维护Java 6。 - Dirk Schumacher

Answer 2

我知道 Enunciate，它在 Jersey/CXF 中表现得非常好 - 但我不知道它是否适用于 SpringMVC。

- Brian Clozel

---

至少它提到了Spring。看起来很有前途。我会设置一个测试。 - Jan

遗憾的是，它还不支持Spring WEB-MVC注解。 - Jan

Answer 3

如果您想自己完成这个任务，可以按照以下步骤进行：

1. 创建一个AnnotationReader实现，用于扫描各种@Path注释
2. 测试它是否能够读取name属性
3. 创建一个Maven mojo，包装这个扫描功能
4. 添加将正则表达式参数（例如{customerId}）映射到有意义的文档目的地的功能，可能通过读取相关的Javadoc来实现。

注释阅读器不需要对现有注释进行任何修改，因此应该很容易建立端点正则表达式列表。结合Javadocs，您应该能够创建一个有用的工具。我肯定会觉得它很有用，也许其他人也会。

- Gary

---

我希望Enunciate能够适用于Spring，但是你的选项看起来是从头开始做的好方法！ - Jan

当前状态：我们使用Doclet API自己完成。如果其他人想要贡献，我们可以在某个公共svn上建立并共享资源。 - Jan

嗨Jan，我对你是如何做到这一点很感兴趣。我们可能会将基于Restlet的API迁移到Spring MVC（虽然我们也在考虑JSR 311 / JAX-RS兼容解决方案）。我认为，能够像使用Javadocs编写代码接口文档那样轻松地生成REST API文档，是将REST API集成到开发周期的最后一步。 - Spanky Quigman