4

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

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

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

为什么大摇大摆必须成为服务器逻辑的一部分？如果我在编辑器中创建 swagger 文件，然后直接将它们提供给UI，它会中断..

据我所知，它甚至使服务器稍微慢了一点，并迫使存在许多笨拙地维护的集成：p 我在这里错过了什么？

4

2 回答 2

4

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

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

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

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

于 2014-10-16T17:50:56.127 回答
4

你可以试试 RAML + ramlev + Abao

步骤应该是

  • 使用您最喜欢的编辑器在 RAML 中编写 API 规范，即。原子，vim
  • 使用ramlev验证您的 RAML
  • 根据 API Spec 实现服务器逻辑
  • 使用Abao验证服务器逻辑
于 2014-10-23T01:06:14.883 回答