java endpoint作用_使用swagger for Java自动生成休息 endpoints

我被赋予了为使用jaxrs开发的大型API找到最佳方法的任务，以便为第三方记录 . 目前，javadoc已经充分记录了该代码 . 我的问题是帮助确定目前为止基于我的研究的最佳方法，并验证我们正在走正确的道路，所以我正在寻找输入，评论或其他框架来查看 . 我确信这是一个常见的用例，其他人会遇到类似的问题，并且非常感谢其他有兴趣和文档经验的人的意见 .

我们有以下要求：

我们没有大量的注释使代码混乱 .

我们可以记录返回类型，例如嵌套对象及其正确的JSON结构 .

我们可以指定 Headers ，链接和元信息(意思是我们需要swagger 2.0而不是1.2)

我们希望尽可能减少时间和成本，但仍保持高质量的文档 .

适用于JDK 8 .

我考虑过以下框架，但是每个框架似乎都有一些主要的缺点，要么使它们难以使用(对于这个项目)，要么我可能会误解 .

The Swagger JAXRS doclet: Link

这个maven插件在构建时工作，并能够根据现有的javadoc注释为我们提供合理的文档 . However, it does not support Swagger 2.0可能会限制在响应中描述 Headers ，这对我们的用例至关重要 . 它能够获取其余服务，而无需使用swagger maven插件所需的@Api或@ApiOperation注释 . 升级它以使用swagger 2.0可能是一项重大任务 .

The Swagger Maven Plugin: Link

该插件在构建时基于注释而不是注释创建swagger文档 . 这需要我们完成整个项目并使用@Api和@ApiOperation进行注释 . 我们可能只会在基类上使用一些注释，但对于 endpoints 的任何描述或 Headers ，我们需要在注释本身中添加详细信息 . 其中许多注释似乎都是重复的，例如我们已经有了@Get或@Post，但仍然需要添加@ApiOperation并描述已经在javadoc中描述的参数 . 垮台是需要时间，并且还会导致代码非常混乱 .

Swagger Core: Link

Swagger核心在运行时工作，这意味着我们无法从现有的javadoc中删除注释 . 它很容易扩展，就像Swagger Maven插件一样，我们可以添加我们自己的读者或规则来添加链接和元信息(或使用我们自己的现有注释) . 缺点是每个方法的描述都需要来自某个地方，所以这些必须添加(更多)注释，这些注释在添加新代码时可能会被遗忘 .

Enunciate: Link

Enunciate对我们不起作用，因为我们需要能够在.NET上使用类似的框架，它也不支持JDK 8(尚未) .

My conclusions so far

swagger jaxrs doclet一直是我们迄今为止所做的一切 . 主要问题是缺乏招摇2.0 . 我们需要能够相应地更新swagger版本，因为其他项目将一起记录(不同语言) . 对我们来说第二好的是Swagger Maven插件，就像自定义跑步者一样，因为这是构建时间，所以应该可以以某种方式访问现有的javadoc注释并将它们添加到生成的swagger中 - 我们可能会侥幸逃脱一些注释在基类上，并使用我们的自定义阅读器从注释中拉出其余的注释(例如描述) . 最后，swagger核心并不真正满足我们的需求，因为我们需要更多的注释来复制现有的javadoc .

有了更新swagger doclet以支持swagger 2.0所需的未知时间，我倾向于使用自定义阅读器的swagger maven插件(任何有关如何阅读javadoc注释的提示都会有用！) . 是否有任何我错过的框架或细节使得我的结论不准确？