我的任务是为使用jaxrs开发的大型API寻找最佳方法，以供第三方记录。该代码目前在javadoc中有很好的文档说明。我的问题是帮助根据迄今为止的研究确定最佳方法，并验证我们走的是正确的道路，因此我正在寻找输入，评论或其他框架。我确信这是一个常见的用例，其他人也会遇到类似的问题，并非常感谢其他有经验的工作人员和文档编写人员的任何投入。
我们有以下要求：
我们没有大量的注释使代码混乱。
我们可以记录返回类型，例如嵌套对象及其正确的JSON结构。
我们可以指定标题，链接和元信息（意思是我们需要2.0而不是1.2）
我们希望尽可能地减少时间和成本，但仍保留高质量的文档。
与JDK 8。
我已经考虑了以下框架，但是每个框架似乎都有一些主要缺点，这些缺点要么使它们难以使用（对于本项目而言），要么使我产生误解。
Swagger JAXRS doclet：Link
这个maven插件在构建时就可以使用，并且能够基于现有的javadoc注释为我们提供合理的文档。 However, it does not support Swagger 2.0可能会限制在响应中描述标头，这对于我们的用例至关重要。它能够获取其余服务，而无需使用swagger maven插件所需的@Api或@ApiOperation批注。升级它以使用swagger 2.0可能是一项艰巨的任务。
Swagger Maven插件：Link
该插件在构建时根据注释而不是注释创建swagger文档。这将要求我们遍历整个项目并使用@Api和@ApiOperation进行注释。我们可能会摆脱仅在基类上的一些注释，但是对于端点的任何描述或标题，我们将需要在注释本身内添加详细信息。这些注解中的许多注解似乎都是重复的，例如，我们已经有@Get或@Post，但是仍然需要添加@ApiOperation并描述javadoc中已经描述的参数。失败的原因是这将花费时间，并且还会导致看起来很混乱的代码。
昂首阔步：Link
Swagger核心在运行时有效，这意味着我们无法从现有的Javadoc中删除注释。就像Swagger Maven插件一样，它很容易扩展，我们可以添加自己的阅读器或规则来添加链接和元信息（或使用我们自己的现有注释）。不利的一面是每种方法的描述都必须来自某个地方，因此必须在（还有更多）注释中添加这些注释，添加新代码时可能会忘记这些注释。
阐明：Link
由于我们需要能够在.NET上使用类似的框架，因此Enunciate不适用于我们，它也不支持JDK 8。
到目前为止我的结论
到目前为止，swagger jaxrs doclet最接近完成我们想要的一切。主要问题是缺乏敏捷2.0。我们需要能够相应地更新swagger版本，就像将一起记录在案的其他项目（不同的语言）一样。对我们来说第二好的是Swagger Maven插件，与自定义运行器一样，由于这是构建时间，因此应该可以以某种方式访问现有的javadoc注释并将其添加到生成的swagger中-我们可能可以避免使用一些注释位于基类上，并使用我们的自定义阅读器从注释中提取其余的注释（例如，描述）。最后，swagger核心并不能真正满足我们的需求，因为我们需要更多的注释来复制现有的javadoc。
由于更新swagger doclet以支持swagger 2.0所需的时间未知，我倾向于使用带有自定义阅读器的swagger maven插件（有关从中阅读javadoc注释的任何技巧都将非常有用！）。我是否错过了任何框架或细节，使我的结论不准确？
最佳答案
每个人都有自己的需求，因此我不会介绍建议的方式来处理您要执行的操作。但是您绝对可以通过创建自定义解析器来扩展swagger-maven-plugin项目，该解析器将通过SPI进行检测。
这不是一项微不足道的任务，但是如果您要这样做，那么就有支持它的基础结构。请在这里查看：https://github.com/swagger-api/swagger-parser#extensions
关于java - 使用Java的swagger自动生成其余端点，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/37397501/