ruby-on-rails - 能够自动更新API文档

Question

我正在开发一个为外部开发人员提供 API 的网站。

每当更新 API(即修改参数、新端点等)时，我都必须手动更新文档。

所以我正在研究如何自动完成此过程。这是我希望实现的目标:一旦我的源代码被更新并提交到我的源代码管理中，某种 API 注册表将被更新。所以我的文档可以是一个应用程序，它引用注册表并向查看器显示最新的 API。

我的网站基于 Ruby on Rails。

Answer 1

RDoc 是根据您的源代码自动生成的，它是 Rails 的默认设置。您的代码需要有详细的文档记录，但如果是，您可以运行

bundle exec rake doc:app

您的应用程序将生成可从 doc/app/index.html 访问的文档。我会看一下，看看这样的文档是否符合您的需要。 “类和模块索引”侧边栏中的链接包含所有方法的列表以及它们的源代码的可扩展 View 。

我使用了一项自定义 rake 任务，将所有文档放在 Rails 公共(public)文件夹中，以便直接从我的网站访问，并允许我添加多个自定义页面。我想对您来说，执行仅解析您的 API 文件的类似操作并不难。

链接:

RDoc Syntax Help

Project on Github