如何自动生成Rails控制器的REST API文档？

Question

如何自动为Rails REST控制器生成API文档？

有没有使用RDoc来做到这一点的示例？

- Teo Choong Ping

Answer 1

你可以尝试我创建的apipie-rails：https://github.com/Pajk/apipie-rails/。它不仅可以生成文档，还可以做更多的事情，更多信息请参见https://github.com/Pajk/apipie-rails/。

- Pavel

---

我看到这个问题时，首先想知道使用DSL是否会在运行时使Rails应用程序变得不必要地臃肿。有人知道答案吗？ - Shyam Habarakada

@ShyamHabarakada 你可以为生产模式生成缓存并关闭参数验证。在这里提到了 https://github.com/Pajk/apipie-rails#static-files - Pavel

Apipie Rails已经被放弃了吗？有很多拉取请求没有得到回复？ - Chris Hough

没有，虽然我承认自己不是世界上最好的项目维护者，但贡献和兴趣水平正在稳步增长，同时也有新功能和错误修复。 - iNecas

Answer 2

我发现https://github.com/zipmark/rspec_api_documentation是一个非常好的工具。它是基于rspec接受测试驱动的，所以你在编写验收测试的同时也在编写文档！双赢！

- glamouracademy

Answer 3

使用 rapi_doc gem。设置非常简单和直接。按照这个教程操作：http://www.rubyglob.com/generating-api-documentation-with-rapi_doc/。

- Dida

---

缺乏文档和测试使得使用起来很困难。 - John Naegle

这看起来过时了，不支持Rails 4运行。 - Matt Connolly

网站现在是404。 - Siwei

Answer 4

我也在寻找一个可以轻松集成到Rails中的好文档工具。最终，我们建立了自己的Rails引擎APIDOCO。

然而，它不会自动生成文档，但你可以很容易地使用它。

- Ameen

Answer 5

你可以使用 "calamum" 这个 Ruby 构建程序，从 YAML 文件定义生成漂亮的 HTML API 文档。 https://github.com/malachheb/calamum

- Mehrez

Answer 6

虽然不是自动的，但我使用RESTful API建模语言或RAML来定义和记录我的API。

有一些Node.js包可以将yaml文件转换为漂亮的HTML文档，比如raml2html。

- Sebastialonso