使用yiic生成应用程序的API文档

International Chinese
1

在团队开发中，我们通常需要把API提供给其它同事参考。

Yii本身有一个生成文档的工具(http://yii.googlecode.com/svn/tags/1.1.5/build/commands/ApiCommand.php)，但是只能生成框架本身的文档。

并不能生成为应用程序（也就是我们自己写的业务逻辑代码）API文档。

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

具体怎么做？(假定我们的应用放在：/var/html/app/)

[list=1]

[*] 先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文件（也可以下载patch959

yiidoc.patch.txt
）修改ApiCommand.php和api/ApiModel.php 两个文件

[*] 然后就可以通过


/var/html/app/protected/yiic api docs/

就会在docs这个目录生成文档了，生成的文档包含应用层的API和框架层的API

[/list]

有几个注意的地方：

  • 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也记入文档，暂时不知道这个有什么好的解法没有。

新手，大家见笑。

2

你这样改太麻烦了，而且修改了官方代码非常不好。

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

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

Yii::import(‘application.commands.ApiCommand’);

class YdocCommand extends ApiCommand

{

}

3

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

更新：

测试了一下，如果想不改动原来的代码，貌似也不太好处理。

首先要继承ClassDoc，覆盖它的getSourceCode的方法；

然后又要继承ApiModel，覆盖它的processClass方法（虽然只是修改一句话，但是还是要把代码拷贝过来，而这一段代码比较复杂一些）；

然后再继承ApiCommand，覆盖renderSourceLink和buildModel。

4

原先早点的版本没有显示源码功能，所以没问题只要继承一下ApiCommand就可以了，现在的问题在于：

ApiModel.php 中 关于 basedoc 基类的定义：

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

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

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

5

刚才尝试了一下，用了不是非常优雅的办法实现了。不改任何原有代码，只需将附件中的 YdocCommand.php 放入

$yii/build/commands/ 目录即可。

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

  1. 针对某个开发好的YII app建立 API 文档

php build ydoc [color="#2E8B57"]/path/to/doc_dir[/color] [color="#FF0000"]/path/to/app/protected[/color]

  1. 针对某个文件建立API文档

php build ydoc [color="#2E8B57"]/path/to/doc_dir[/color] [color="#FF0000"]/path/to/file[/color]

特别说明：

红色部分可以是任意文件或目录，请使用绝对路径，如果使用相对路径则默认会当作在 YII_PATH，比如

输入 framework/base 就相当于 YII_PATH/framework/base

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

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

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

6

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

7

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

8

有个扩展专门搞这个的：yiiDocGenerator

yii官方扩展库中的位置：yiidocsgenerator

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

9

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