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