用于spring-mvc rest api文档的javadoc-like工具？

Question

我一直在寻找类似javadoc的REST API文档工具.我已经在javadoc中记录了我的其余控制器,我认为为前端开发人员创建一个api文档会很好.

我认为还没有工具.那么有人有想法如何完成这项任务吗？我想过使用经典的javadoc工具并添加一些spring/rest特定的逻辑.但我还不确定我是否还需要一些特殊的标记或者可能存在哪些陷阱.最后,我想要一些可以集成到maven站点生命周期中的工具,但这应该不难实现.

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

我很感激有关相关项目的任何提示,已经存在的工具或只是您使用javadoc工具的经验!

Answer 1

如果你想自己做这件事，你可以这样处理：

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

注释阅读器不必对现有注释进行任何修改，因此构建端点正则表达式列表应该很简单。结合 Javadocs，您应该能够创建一个有用的工具。我当然会发现它很有用，也许其他人也会。