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