我的任务是为使用 jaxrs 开发的大型 API 寻找最佳方式，以便为第三方提供文档。该代码目前已使用 javadoc 进行了详细记录。我的问题是帮助确定基于我迄今为止的研究的最佳方法，并验证我们是否走在正确的道路上，所以我正在寻找输入、评论或其他框架来查看。我确信这是一个常见的用例，其他人也会遇到类似的问题，并且非常感谢其他有招摇和文档经验的人提供的任何意见。
我们有以下要求：
- 我们没有大量的注释使代码混乱。
- 我们可以记录返回类型，例如嵌套对象及其正确的 JSON 结构。
- 我们可以指定标题、链接和元信息（这意味着我们需要 swagger 2.0 而不是 1.2）
- 我们希望尽可能减少时间和成本，但仍保留高质量的文档。
- 适用于 JDK 8。
我考虑了以下框架，但每个框架似乎都有一些主要缺点，要么使它们难以使用（对于这个项目），要么我可能误解了。
Swagger JAXRS doclet：链接
这个 maven 插件在构建时工作，能够根据现有的 javadoc 注释为我们提供合理的文档。但是，它不支持 Swagger 2.0，这可能会限制在响应中描述标头，这对我们的用例至关重要。它能够在不需要 swagger maven 插件所需的 @Api 或 @ApiOperation 注释的情况下获取其余服务。升级它以使用 swagger 2.0 可能是一项艰巨的任务。
Swagger Maven 插件：链接
该插件在构建时基于注释而不是注释创建 swagger 文档。这需要我们遍历整个项目并使用@Api 和@ApiOperation 进行注释。我们可能会避免一些仅在基类上的注释，但是对于端点的任何描述或标题，我们将需要在注释本身中添加详细信息。其中许多注解似乎是重复的，例如我们已经有了@Get 或@Post，但还需要添加@ApiOperation 并描述已经在javadoc 中描述的参数。缺点是这需要时间，并且还会导致看起来非常混乱的代码。
招摇核心：链接
Swagger 核心在运行时工作，这意味着我们无法从现有的 javadoc 中删除注释。它很容易扩展，就像 Swagger Maven 插件一样，我们可以添加自己的阅读器或规则来添加链接和元信息（或使用我们自己现有的注释）。缺点是每个方法的描述都需要来自某个地方，因此必须在（更多）注释中添加这些注释，这些注释在添加新代码时可能会被遗忘。
发声：链接
Enunciate 对我们不起作用，因为我们需要能够在 .NET 上使用类似的框架，而且它也不支持 JDK 8（目前）。
到目前为止我的结论
到目前为止，swagger jaxrs doclet 是最接近我们想要的一切。主要问题是缺乏 swagger 2.0。我们需要能够相应地更新 swagger 版本，因为将一起记录的其他项目（不同语言）会这样做。对我们来说第二好的是 Swagger Maven 插件，就像使用自定义运行器一样，因为这是构建时间，应该可以以某种方式访问现有的 javadoc 注释并将它们添加到生成的 swagger 中 - 我们可能会侥幸逃脱一些注释在基类上，并使用我们的自定义阅读器从评论中提取其余的（例如描述）。最后，swagger 核心并不能真正满足我们的需求，因为我们需要更多的注释来复制现有的 javadoc。
由于更新 swagger doclet 以支持 swagger 2.0 所需的时间未知，我倾向于使用自定义阅读器的 swagger maven 插件（有关如何从中读取 javadoc 注释的任何提示都会很有用！）。是否有任何我遗漏的框架或细节使我的结论不准确？