如何为我的Rails 3 REST服务生成公共文档？
所以我在使用Devise作为我的身份验证机制在Rails 3中构建应用程序。我拥有所有的控制器和视图。我们的网站正在嗡嗡作响。现在我们想将我们的路线导出到第三方开发者。问题在于如何。如何为我的Rails 3 REST服务生成公共文档？
下面是我认为我需要弄清楚的事情列表。
第三方认证。我正在努力使自己脑中的事情变成我需要做的事情。我们有一个现有的用户群，使用Devise身份验证模型为他们创建了令牌。现在我需要提供某种安全性。我目前的思路是建立一个OAuth提供程序来管理私钥，然后以某种方式将我们的Web应用程序设置为第三方开发人员可以访问的应用程序之一。这是正确的思路还是我过度设计它？
为我们的REST端点生成面向公众的文档。虽然内部开发者的耙路线很好，但我认为我们需要更多的东西来满足swagger-ui的需求。问题是rails不会为swagger-ui生成适当的json/xml调用。据我所知，这是真正的REST服务所必需的。如资源列表和资源上列出的操作。
在此感谢您提供给我的任何方向！
如果您的用户有安全元素，我一定会推荐OAuth。也就是说，您希望某人能够通过其服务编辑多个用户详细信息，然后使用三方OAuth（提供商，用户，客户端）。否则，请转到双腿OAuth（提供商，客户端）。
如果要实施3腿OAuth API，那么我写了一个可用的教程here。它使用Devise和Oauth2。
至于文档，我会尽可能编写自定义文档，而不是依赖工具。 Twitter有一个很好的文档API，我用它作为我编写的RESTful API的基础。
该指南非常有帮助。有一点是不清楚的地方，“oauthenticate：interactive => false”我试图把它放到我的application_controller中，因为我希望所有的东西都需要oauth，但是它不能识别它。我想允许登录或OAuth，因为我的网络应用程序将使用登录与API交谈。 – Altonymous
如果您将交互设置为true，那么它应该允许API和登录访问。 – Gazler
这就是我所做的。一切“似乎”都在起作用。当我们的QA获得一些免费周期时，我们将进行一些测试。这是我提前做的一个副项目。 :-P谢谢Gazler。我给你信贷，但如果我们的测试人员发现任何问题，我会告诉你！ – Altonymous
我对Swagger（我在Wordnik上工作）有偏见，并指出我们将添加ruby服务器支持来自动生成描述图层，就像我们使用Scala一样。
越早发生越好。在我看来，真正需要做的就是生成资源的一些方式，操作响应和swagger-ui应该可以工作。 – Altonymous
在这方面还没有看到任何更新...事情如何发展？ – Altonymous
@Altonymous我正在开发Ruby注解支持。按照twitter上的swagger_doc获取该方面的更新。 – Zeke
https://github.com/richhollis/swagger-docs – nycynik