42

Spring REST Docs 最近发布，文档说：

这种方法使您摆脱了 Swagger 等工具所施加的限制

所以，我想问一下，与 Swagger 相比，Spring REST Docs 何时更适合使用，以及它释放了哪些限制。

4

5 回答 5

30

我刚刚在这里看到了一个演示文稿，其中涉及您的问题以及其他主题：

https://www.youtube.com/watch?v=k5ncCJBarRI&t=26m58s

  • Swagger 根本不支持超媒体/它以 URI 为中心

  • Swagger 检查代码的方法可能落后于您的代码。有可能对您的代码进行更改，而 Swagger 无法理解并且在 Swagger 更新之前无法正确处理。

  • Swagger 需要大量的注解，并且在注解中包含你想要的 api 文档中的描述性文本是很痛苦的。

  • Swagger 在检查您的代码时无法弄清楚一些事情。

无论如何，这些只是几点。主持人在讨论它时做得比我好得多。

于 2016-01-16T11:07:21.213 回答
13

我想我会加入更多关于 Swagger 的背景信息，它是什么，不是什么。我相信这可能有助于回答您的问题。

Swagger 2.0 正在被 Microsoft Azure、Paypal、SwaggerHub.com、DynamicApis.com 等许多大牌和大平台采用……要记住的是，Swagger 是一个非常简单的规范。它不是一个框架。有很多框架可以生成 Swagger 输出，这些输出会在您的代码中爬行，查看您的 API 信息，以便构建代表您的 API 的 Swagger 2.0 JSON 文件。您在其上看到 API 的 Swagger UI 直接从此 Swagger 2.0 JSON 文件驱动。 提琴检查一下

需要注意的是，创建一个允许您“使用 swagger”的框架并不是 Swagger 必须如何工作的（即它完全取决于第 3 方框架的实现）。如果您用于生成 Swagger 2.0 文档和 UI 的框架不适合您，那么您应该能够找到另一个生成 Swagger 工件的框架并交换技术。

希望这可以帮助。

于 2016-01-25T16:45:03.193 回答
8

来自Spring REST 文档：

Spring REST Docs 的目的是帮助您为 RESTful 服务生成准确且可读的文档

这种测试驱动的方法有助于保证服务文档的准确性。如果片段不正确，则生成它的测试将失败。

Spring REST 文档的优点：

  • 文档是在测试代码中编写的，因此它不会用大量注释和描述使主代码过载
  • 生成的文档和示例是准确的，因为必须通过相关测试
  • 文档可以提供更具体和描述性的片段
  • 格式适合出版

Spring REST 文档的缺点：

  • 需要更多的工作
  • 文档提供请求/响应示例，但不提供用于修改和尝试请求的交互式工具

招摇的优点：

  • 从代码中快速、自动生成
  • 交互式请求执行 - 可用于验收测试
  • 围绕OpenAPI规范构建

招摇的缺点：

  • 对于更具描述性的文档，它将需要大量注释
  • 测试与文档无关，因此有时文档可能会偏离现实
于 2018-10-30T21:06:21.947 回答
6

swagger 和特定的弹簧堆栈有一些限制。

例如：在您的请求映射中使用“param”，您可以定义多个具有相同 url ans 的方法，从而简化您的代码。但是大摇大摆地向您展示一种方法

于 2016-01-15T20:31:16.303 回答
0

Swagger 的一个缺点是：它无法处理具有循环依赖关系的模型。如果模型具有循环依赖并且启用了 swagger，则 Spring Boot 服务器会崩溃。

于 2019-06-13T05:57:36.793 回答