如何为Rails 3 REST服务生成公共文档?

时间:2011-09-06 21:50:03

标签: ruby-on-rails ruby-on-rails-3 rest documentation routes

所以我正在使用Devise作为我的身份验证机制在Rails 3中构建一个应用程序。我的所有控制器和视图都在工作。我们的网站正在嗡嗡作响。现在我们想将我们的路线导出到第三方开发商。问题是如何。

以下是我认为需要弄清楚的事项清单。

  1. 第三方身份验证。我试图直接把它弄清楚我需要做什么。我们有一个现有的用户群,并且已经使用Devise身份验证模型为所有用户生成了令牌。现在我需要提供某种安全性。我目前的想法是设置OAuth提供程序来管理私钥,然后以某种方式将我们的Web应用程序设置为第三方开发人员可以访问的应用程序之一。这是正确的思路吗?还是我过度设计了它?

  2. 为我们的REST端点生成面向公众的文档。虽然rake路线对内部开发人员来说很好,但我真的认为我们需要更多的东西,比如swagger-ui。问题是rails没有为swagger-ui生成适当的json / xml调用。根据我的理解,这是真正的REST服务所必需的。例如资源列表和资源上的操作列表。

  3. 提前感谢您在这些舞台上给我的任何方向!

2 个答案:

答案 0 :(得分:4)

我对Swagger有偏见(我在Wordnik上工作)并指出我们将添加ruby服务器支持以自动生成描述层,就像我们使用Scala一样。

答案 1 :(得分:0)

如果您的用户有安全元素,我肯定会推荐OAuth。也就是说,您希望某人能够通过他们的服务编辑多个用户详细信息,然后使用3-legged OAuth(提供者,用户,客户端)。否则,请选择2脚OAuth(提供商,客户。)

如果你想实现一个三足的OAuth API,那么我写了一个可用的教程here。它使用Devise和Oauth2。

至于文档,我会尽可能地编写自定义文档而不是依赖于工具。 Twitter有一个记录良好的API,我将其作为我编写的RESTful API的基础。