Yii Framework Forum: 使用yiic生成应用程序的API文档 - Yii Framework Forum

Jump to content

Page 1 of 1
  • You cannot start a new topic
  • You cannot reply to this topic

使用yiic生成应用程序的API文档 Rate Topic: ***** 1 Votes

#1 User is offline   robhsiao 

  • Newbie
  • Yii
  • Group: Members
  • Posts: 7
  • Joined: 02-November 10

Posted 20 November 2010 - 04:58 AM

在团队开发中,我们通常需要把API提供给其它同事参考。
Yii本身有一个生成文档的工具(http://yii.googlecod.../ApiCommand.php),但是只能生成框架本身的文档。
并不能生成为应用程序(也就是我们自己写的业务逻辑代码)API文档。

Yii生成的文档很漂亮,并且不需要依赖 phpDocumentor。于是我自己改了改相关文件的源代码,通过Yii也可以生成应用程序的API文档。

具体怎么做?(假定我们的应用放在:/var/html/app/)
  • 先checkout build工具:
    svn co http://yii.googlecode.com/svn/tags/1.1.5/build/commands/

  • 然后将里边的生成API的部分文件拷贝出来:
    cp -r ApiCommand.php api /var/html/app/protected/commands/

  • 进入到应用程序目录/var/html/app/protected/commands/,参考这个patch文件(也可以下载patchAttached File  yiidoc.patch.txt (2.38K)
    Number of downloads: 18)修改ApiCommand.php和api/ApiModel.php 两个文件
  • 然后就可以通过
    /var/html/app/protected/yiic api docs/
    就会在docs这个目录生成文档了,生成的文档包含应用层的API和框架层的API


有几个注意的地方:
  • patch里边的 baseAppSourceUrl,可以通过它配置你公司内部的WebSVN或Trac Browser之类的工具URL。
  • patch中的buildModel这个函数里边包含了一个数组,array('models','components','controllers','extensions'),这将意味着生成的文档会包括这些目录(/var/html/app/protected/{models,components,controllers,extensions})下面的类,大家可以自己修改,比如把controllers目录加到这个数组,生成的文档也会包含controller的API。但是千万不要把 views 之类的目录也加进去,否则会报错。
  • 类的名字要全局(应用层+框架层)范围唯一。原因是"yiic api"命令会通过include_once把涉及的源文件全部加载进,再通过reflection得到类的信息,如果有不同的类使用同样的类名,PHP会报错: "Cannot redeclare class XXX"。比如我就遇到因为多个modules的话就会有多个"DefaultController"类,没有办法把modules的API也记入文档,暂时不知道这个有什么好的解法没有。


新手,大家见笑。
0

#2 User is offline   hightman 

  • Junior Member
  • Pip
  • Yii
  • Group: Members
  • Posts: 44
  • Joined: 23-August 09

Posted 20 November 2010 - 09:14 AM

你这样改太麻烦了,而且修改了官方代码非常不好。
其实可以简单继承 ApiCommand 并覆盖部分方法即可,我之前有这样做过,但后来YII修改了一些路径的计算方式导致我的代码临时不能用了,暂时没时间也没去弄它了。

类似以下的方法去弄,尽量避免直接修改官方提供的代码以免导致不兼容或引起其它BUG。

Yii::import('application.commands.ApiCommand');
class YdocCommand extends ApiCommand
{
}
0

#3 User is offline   robhsiao 

  • Newbie
  • Yii
  • Group: Members
  • Posts: 7
  • Joined: 02-November 10

Posted 20 November 2010 - 09:50 AM

噢天啊,我大费周章,hightman几句话就搞定。佩服啊。是CU的hightman吗?

----------

更新:

测试了一下,如果想不改动原来的代码,貌似也不太好处理。
首先要继承ClassDoc,覆盖它的getSourceCode的方法;
然后又要继承ApiModel,覆盖它的processClass方法(虽然只是修改一句话,但是还是要把代码拷贝过来,而这一段代码比较复杂一些);
然后再继承ApiCommand,覆盖renderSourceLink和buildModel。

This post has been edited by robhsiao: 20 November 2010 - 11:28 AM

0

#4 User is offline   hightman 

  • Junior Member
  • Pip
  • Yii
  • Group: Members
  • Posts: 44
  • Joined: 23-August 09

Posted 20 November 2010 - 10:18 PM

原先早点的版本没有显示源码功能,所以没问题只要继承一下ApiCommand就可以了,现在的问题在于:
ApiModel.php 中 关于 basedoc 基类的定义:

在 loadSource() 时把路径中的 YII_PATH 清除,在 getSourceCode() 里的前头补上 YII_PATH。

以至于如果我的 sourcePath 并不在 YII_PATH 底下时就出错。。。。

稍后我再看看有没有什么更简单的方法解决这个问题,或者提交官方建议修正这个限制,当 sourcePath 不包含YII_PATH时也能支持一下。
0

#5 User is offline   hightman 

  • Junior Member
  • Pip
  • Yii
  • Group: Members
  • Posts: 44
  • Joined: 23-August 09

Posted 20 November 2010 - 11:35 PM

刚才尝试了一下,用了不是非常优雅的办法实现了。不改任何原有代码,只需将附件中的 YdocCommand.php 放入
$yii/build/commands/ 目录即可。

在 build/ 目录下的使用方式:

1. 针对某个开发好的YII app建立 API 文档
php build ydoc /path/to/doc_dir /path/to/app/protected

2. 针对某个文件建立API文档
php build ydoc /path/to/doc_dir /path/to/file

特别说明:
红色部分可以是任意文件或目录,请使用绝对路径,如果使用相对路径则默认会当作在 YII_PATH,比如
输入 framework/base 就相当于 YII_PATH/framework/base

自动描扫目录下的文件的时候会排除目录名为 views 或 view 的文件夹,同时排除命名没有以大写字母开头的 .php 文件。

此外,如果检测到生成DOC的目录是 protected 结尾,那么会自动把框架基础文件也加进去,避免一些无法识别的链接。


--手注:其实如果官方团队稍作修改,应该可以更完美的支持APP文档生成。

Attached File(s)


2

#6 User is offline   robhsiao 

  • Newbie
  • Yii
  • Group: Members
  • Posts: 7
  • Joined: 02-November 10

Posted 21 November 2010 - 01:42 AM

嗯,期待Yii Team在这方面也有所改进,同时感谢hightman指点
0

#7 User is offline   phpii 

  • Newbie
  • Yii
  • Group: Members
  • Posts: 1
  • Joined: 06-October 12

Posted 07 December 2012 - 05:47 AM

hightman这里提到的方法,现在需要更新一下了。。
0

#8 User is offline   yiqing95 

  • Advanced Member
  • PipPipPip
  • Yii
  • Group: Members
  • Posts: 586
  • Joined: 27-December 10
  • Location:china

Posted 07 December 2012 - 11:14 PM

有个扩展专门搞这个的:yiiDocGenerator
yii官方扩展库中的位置:yiidocsgenerator

并且还有wiki 教你如何遵循yii 注释规范的 wiki page
0

#9 User is offline   Alphaschao 

  • Newbie
  • Yii
  • Group: Members
  • Posts: 4
  • Joined: 19-February 13

Posted 19 February 2013 - 08:02 PM

请问1.1.12版本该如何生成应用程序的API?
0

Share this topic:


Page 1 of 1
  • You cannot start a new topic
  • You cannot reply to this topic

1 User(s) are reading this topic
0 members, 1 guests, 0 anonymous users