自己写 Ruby/Rails Api 文档的生成器

July 12, 2013 22:00


rails 写api一直纠结要写文档给别人看,文档嘛,写完代码后真心不想写,于是就要利用我写代码时的注释来生成一个简单的文档

rdoc吗,他对rails的api弄的不怎么好看,也非常混乱,于是开始自己写一个简单的生成器

一般我的api代码都会如下

class Api::UsersController < Api::BaseController
  # 取得用户列表
  #
  # Params:
  # page: 页数
  # perpage: 每页数量
  # Return:
  # xxxx
  def index
    # ...
  end
end

然后我希望自动生成文档,显示上面的api说明, 参数,返回值,然后最重要的是api请求地址和请求方法

对于请求地址和请求方法,rdoc打死也生成不出来的,于是开始写自己的文档生成器

首先要取得所有的action, 先通过Dir["path/to/controoer/*/.rb"]取得所有的controller,然后加载文件,根据文件名得到类名,然后将基类的publicinstancemethods - 当前类的publicinstancemethods得到当前类所有的public实例方法,也就是所有action了

得到action,接下来就要得到代码上面的注释,通过循环action名字,然后isntancemethod(:name)取得这个action,然后通过action.sourcelocation取得代码所在文件及行数

上面得出来已经明了了,向上一行行的取就可以得到所有注释了,解析一下就好了,下面就是关系的action地址和请求方法了

地址和方法,我们可以通过rails的routes中取得,先从Rails.application.routes中取得所有的routes,然后再通过与controller#action来匹配,匹配到了就可以得到path与请求方法了

最后我们再用erb什么的写一个模板,然后把上面得到的数据传入模板,一个简单的api文档就出来了,肃然,如果模板写的好,可以做出非常美观的文档

最后附上我写的一个rails api文档生成器:api doc generate

上面的gem通过rake doc:api可以生成一个文档在Rails的tmp目录下面。当然这个gem生成的文档也非常的简单的,不过用来参量还是可以的,至于源代码。。还是把gem安装好再看里面的代码吧,这个真还没放到github上。。

Comments: