Rails Rails 有什么好的生成 API Doc 的工具么

birbird · 2015年06月24日 · 最后由 lyfi2003 回复于 2016年05月16日 · 3778 次阅读

找了一下,发现了这么几个,但都不满意 https://github.com/zipmark/rspec_api_documentation https://github.com/Apipie/apipie-rails https://github.com/richhollis/swagger-docs

关键在如何生成 Response 的 Doc,最好是能从 jbuilder(或者产生 Response json 的代码上) 生成 API Doc,而不要硬贴一个 Response example 上去,那样日后维护起来容易错。

请问有这样的工具么?

共收到 8 条回复

可以看一下 lina, Rails + jbuilder 下的 API 生成方案, 也许能有所收获

如果用了grape,可以用 grape-swagger

RAML+api console

非常感谢楼上的各位,分享了很多好东西。 Lina 是最符合我最初的问题描述的,值得试用。 恕我愚钝,不太搞得懂 https://github.com/r7kamura/autodoc 就没管了。

另外三个东西,swagger,BulePrint,RAML 正好是目前最有影响力的三个 API design tool,都被朋友们提到了。 在了解他们的过程中,我也接受了单独写一份 API 文档的思路,而不是觉得一定要自动生成文档。 因为在最开始设计讨论的时候,总要有个记录方式,应该是先设计好了再来实现,后端的实现还不存在,生成文档就是无根之水。

如果先写 API Spec,那较量的的就是这种描述方式是不是亲近人类思维,同时配套的工具是不是强大(比如编辑 API Spec 的工具,生成前后端代码的工具)。初步印象,觉得 RAML 最对胃口,那就先试试他了。

这里,也提供几个对比测评,以享后来者 http://www.mikestowe.com/2014/07/raml-vs-swagger-vs-api-blueprint.php http://apievangelist.com/2014/03/08/hello-world-product-api-with-blueprint-raml-and-swagger/

再次感谢各位。

#1楼 @lyfi2003 似乎停止更新了?

#7楼 @feng88724 最近有一些新的更新计划, 但太忙了, 暂时没时间搞. 有问题多交流!

需要 登录 后方可回复, 如果你还没有账号请点击这里 注册