与Swagger相比，使用Spring REST Docs有什么好处

Question

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

  

这种方法可以让您摆脱Swagger等工具带来的限制

所以，我想问一下，当Spring REST Docs与Swagger比较时，以及它可以解除哪些限制。

Answer 1

我刚刚在这里看到了一个介绍其他主题的问题：

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

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

• Swagger检查代码的方法可能会落后于您的代码。您可以更改代码，Swagger无法理解并且在Swagger更新之前无法正常处理。

• Swagger需要大量注释，并且在注释中将所需的描述性文本包含在api文档中会很痛苦。

• Swagger可以通过检查您的代码来解决一些问题。

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

Answer 2

我想我会想要提供更多关于Swagger的内容，它是什么，以及它不是什么。我相信这可能有助于回答你的问题。

Swagger 2.0正被许多大牌和大平台采用，如Microsoft Azure，Paypal，SwaggerHub.com，DynamicApis.com等......需要记住的是Swagger is very simply a specification。它不是一个框架。有很多frameworks用于生成Swagger输出，可以通过代码查看您的API信息，以构建代表您的API的Swagger 2.0 JSON文件。您看到API的Swagger UI直接来自此Swagger 2.0 JSON文件。 小提琴把它检查出来

重要的是要注意，为了让你“使用招摇”而创建的框架并不是Swagger必须工作的方式（即完全取决于第三方框架的实现）。如果您用来生成Swagger 2.0文档和UI的框架不适合您，那么您应该能够找到另一个生成Swagger工件的框架并将这些技术交换出来。

希望这有帮助。

Answer 3

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

例如：使用＆＃34; param＆＃34;在您的请求映射中，您可以使用相同的URL定义多个方法，以简化您的代码。 但招摇只是向你展示一种方法

Answer 4

来自Spring REST docs：

  

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

     

这种测试驱动的方法有助于确保服务文档的准确性。如果摘要不正确，则产生该摘要的测试将失败。

Spring REST文档的优势：

• 文档是用测试代码编写的，因此它不会使带有很多注释和描述的主代码超载
• 生成的文档和示例准确无误，因为相关测试必须通过
• 文档可以提供更具体和更具描述性的摘要
• 格式适合发布

Spring REST文档的缺点：

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

昂首阔步的优势：

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

招摇劣势：

• 要获取更具描述性的文档，将需要大量注释
• 测试与文档无关，因此有时文档可能与现实不符

Answer 5

Swagger的一个缺点是：它不能处理具有周期性依赖关系的模型。如果模型具有周期性依赖性，并且启用了swagger，则Spring Boot服务器将崩溃。