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

Question

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

这种方法将您从像Swagger这样的工具强加的限制中解放出来

所以，我想问一下，与Swagger相比，SpringREST文档什么时候更适合使用，以及它释放了哪些限制。

Answer 1

来自Spring REST文档：

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

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

Spring REST文档优势：

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

Spring REST文档的缺点：

• 需要更多的工作

招摇过市的优势：

• 从代码快速自动生成

招摇过市的缺点：

• 对于更具描述性的留档，需要大量注释
• 测试与留档无关，所以有时记录可能会偏离现实

Answer 2

我想我会插话说，给斯威格多一点背景，它是什么，它不是什么。我相信这可能有助于回答你的问题。

Swagger 2.0正在被许多大牌和大平台采用，如微软Azure、贝宝、SwaggerHub.com、DynamicApis.com等...需要记住的是，Swagger只是一个规范。它不是一个框架。有很多框架是为了生成Swagger输出而构建的，这些输出可以爬过你的代码查看你的应用编程接口信息，以便构建代表你的应用编程接口的Swagger 2.0 JSON文件。你在上面看到的Swagger UI是直接从这个Swagger 2.0 JSON文件驱动的

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

希望这有帮助。

Answer 3

我刚才在这里看到一个介绍，涉及到您的问题以及其他主题：

https://www.youtube.com/watch?v=k5ncCJBarRI

>

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

Swagger检查代码的方法可能会落后于代码。在您的代码中进行一个Swigger无法理解的更改是可能的，并且在Swigger得到更新之前无法正确处理。

Swagger需要大量注释，在注释中包含api文档中所需的描述性文本是一件痛苦的事情。

有些事情斯瓦格无法通过检查您的代码来解决。

无论如何，这些只是几点。演讲者在讨论这件事方面比我做得好得多。