api - swagger 究竟是什么？为什么在线编辑器不运行请求？

Question

过去几天我一直在试图了解我是否应该使用 api 蓝图、RAML 或 swagger。

看起来 swagger 拥有最大的社区，但我越看越觉得它缺乏文档(我被迫多次查看代码以尝试将其与我当前的项目集成)，许多 github 问题和 stackoverflow问题没有答案。

我有可能在这里遗漏了什么吗？
我想要的只是一个帮助我编写 API 文档和测试端点的工具。

为什么必须swagger成为服务器逻辑的一部分？？如果我在 the editor 中创建 swagger 文件然后将它们送达 UI直接就断了。。

据我所知，它甚至使服务器稍微变慢，并强制存在许多笨拙维护的集成:p 我在这里缺少什么？

Answer 1

我们正在努力改进 Swagger 的文档。当许多项目是社区驱动的而不是由单个组织管理时，这就有点困难了。

我们实际上尝试快速回复 github 上的问题(我们并不总是成功)，并且我们有自己的 google 小组来解决一般问题，因此我们对 stackoverflow 的关注较少。

你提到的编辑器是一个新工具，作为 Swagger 2.0 工作的一部分，它还不是最终版本。因此，它仍然有一些错误和缺失的功能。 UI 也在适应 Swagger 2.0 的过程中，同样的限制也适用于它。

您当然不必将它与您的服务器集成，您可以静态公开文档。将其与服务器集成的优势在于，如果 API 发生变化，则更易于维护。