与 Swagger 相比，使用 Spring REST Docs 有什么好处
What is the benefit of using Spring REST Docs comparing to Swagger
Spring REST Docs 最近发布，文档说：
This approach frees you from the limitations imposed by tools like Swagger
所以，我想问一下什么时候 Spring REST Docs 比 Swagger 更可取，它释放了哪些限制。
swagger 和特定的 spring 堆栈存在一些限制。
例如：在您的请求映射中使用 "param"，您可以定义多个具有相同 url ans 的方法，从而简化您的代码。
但是 swagger 只告诉你一个方法
我刚刚在这里看到了一个涉及您的问题以及其他主题的演示文稿：
https://www.youtube.com/watch?v=k5ncCJBarRI&t=26m58s
Swagger 根本不支持超媒体/它以 URI 为中心
Swagger 检查代码的方法可能会滞后于您的代码。在 Swagger 更新之前，Swagger 可能无法理解并且无法正确处理您的代码。
Swagger 需要大量注释，在注释中包含您想要的 api 文档中的描述性文本是很痛苦的。
Swagger 无法通过检查您的代码弄清楚一些事情。
无论如何，这些只是几点。主持人比我讨论得更好。
我想我会插话来提供更多关于 Swagger 的背景信息，它是什么，它不是什么。我相信这可能有助于回答您的问题。
Swagger 2.0 已被许多知名企业和大型平台采用，例如 Microsoft Azure、Paypal、SwaggerHub.com、DynamicApis.com 等...需要记住的是 Swagger is very simply a specification. It is not a framework. There are a lot of frameworks 在那里构建以生成 Swagger 输出，该输出通过查看您的 API 信息的代码爬行，以便构建代表您的 API 的 Swagger 2.0 JSON 文件。您在 API 上看到的 Swagger UI 是直接从这个 Swagger 2.0 JSON 文件驱动的。 fiddler 看看
重要的是要注意，为了让您 "use swagger" 而创建的框架并不是 Swagger 的工作方式（即它完全取决于第 3 方框架的实现）。如果您用来生成 Swagger 2.0 文档的框架 UI 不适合您，那么您应该能够找到另一个生成 Swagger 工件的框架并交换技术。
希望对您有所帮助。
The aim of Spring REST Docs is to help you to produce documentation for your RESTful services that is accurate and readable
This test-driven approach helps to guarantee the accuracy of your service’s documentation. If a snippet is incorrect the test that produces it will fail.
Spring REST 文档优势：
- 文档是在测试代码中编写的，因此它不会用大量注释和描述使主代码过载
- 生成的文档和示例是准确的，因为相关测试必须通过
- 文档可以提供更具体和描述性的片段
- 格式适合发布
Spring REST 文档缺点：
- 需要更多工作
- 文档提供 request/response 示例，但不提供交互式工具来修改和试用请求
招摇优势：
- 从代码快速自动生成
- 交互式请求执行 - 可用于验收测试
- 围绕 OpenAPI 规范构建
Swagger 缺点：
- 要获得更多描述性文档，需要大量注释
- 测试与文档无关，因此有时文档可能与实际情况不同
Swagger 的一个缺点是：它无法处理具有循环依赖性的模型。如果模型具有循环依赖性并且启用了 swagger，则 spring 引导服务器崩溃。
Spring REST Docs 最近发布，文档说：
This approach frees you from the limitations imposed by tools like Swagger
所以，我想问一下什么时候 Spring REST Docs 比 Swagger 更可取，它释放了哪些限制。
swagger 和特定的 spring 堆栈存在一些限制。
例如：在您的请求映射中使用 "param"，您可以定义多个具有相同 url ans 的方法，从而简化您的代码。 但是 swagger 只告诉你一个方法
我刚刚在这里看到了一个涉及您的问题以及其他主题的演示文稿：
https://www.youtube.com/watch?v=k5ncCJBarRI&t=26m58s
Swagger 根本不支持超媒体/它以 URI 为中心
Swagger 检查代码的方法可能会滞后于您的代码。在 Swagger 更新之前，Swagger 可能无法理解并且无法正确处理您的代码。
Swagger 需要大量注释，在注释中包含您想要的 api 文档中的描述性文本是很痛苦的。
Swagger 无法通过检查您的代码弄清楚一些事情。
无论如何，这些只是几点。主持人比我讨论得更好。
我想我会插话来提供更多关于 Swagger 的背景信息，它是什么，它不是什么。我相信这可能有助于回答您的问题。
Swagger 2.0 已被许多知名企业和大型平台采用，例如 Microsoft Azure、Paypal、SwaggerHub.com、DynamicApis.com 等...需要记住的是 Swagger is very simply a specification. It is not a framework. There are a lot of frameworks 在那里构建以生成 Swagger 输出，该输出通过查看您的 API 信息的代码爬行，以便构建代表您的 API 的 Swagger 2.0 JSON 文件。您在 API 上看到的 Swagger UI 是直接从这个 Swagger 2.0 JSON 文件驱动的。 fiddler 看看
重要的是要注意，为了让您 "use swagger" 而创建的框架并不是 Swagger 的工作方式（即它完全取决于第 3 方框架的实现）。如果您用来生成 Swagger 2.0 文档的框架 UI 不适合您，那么您应该能够找到另一个生成 Swagger 工件的框架并交换技术。
希望对您有所帮助。
The aim of Spring REST Docs is to help you to produce documentation for your RESTful services that is accurate and readable
This test-driven approach helps to guarantee the accuracy of your service’s documentation. If a snippet is incorrect the test that produces it will fail.
Spring REST 文档优势：
- 文档是在测试代码中编写的，因此它不会用大量注释和描述使主代码过载
- 生成的文档和示例是准确的，因为相关测试必须通过
- 文档可以提供更具体和描述性的片段
- 格式适合发布
Spring REST 文档缺点：
- 需要更多工作
- 文档提供 request/response 示例，但不提供交互式工具来修改和试用请求
招摇优势：
- 从代码快速自动生成
- 交互式请求执行 - 可用于验收测试
- 围绕 OpenAPI 规范构建
Swagger 缺点：
- 要获得更多描述性文档，需要大量注释
- 测试与文档无关，因此有时文档可能与实际情况不同
Swagger 的一个缺点是：它无法处理具有循环依赖性的模型。如果模型具有循环依赖性并且启用了 swagger，则 spring 引导服务器崩溃。