开发 PHP 不像开发 Java 有较强的文档注释规范,通过注释可以便捷地生成接口文档。
我在寻找 PHP 接口文档工具时使用过 phpDoc,页面效果不怎么好。辗转使用了 phpDocumentor,页面效果可以接受。
使用 phpDocumentor 步骤(仅在 Windows 系统验证通过):
首先安装 php5
下载 phpDocumentor.phar 文件
访问百度盘 http://pan.baidu.com/s/1bnErGXh 下载 phar 文件。
在 PHP5 目录(php.ini 所在的目录)下创建 phar 目录,并把 phpDocumentor.phar 移动到该目录。
进入 PHP5 目录,打开 cmd 命令窗口,执行 phpDocumentor 命令
php phar\phpDocumentor.phar -d D:\ran\framework -t D:\zhengxianjun_cdn\www\ran-api
-d 参数表示源代码目录
-t 参数表示生成的接口文档存放目录
命令执行完成之后会在 D:\zhengxianjun_cdn\www\ran-api\reports\errors.html 记录下源代码中接口描述不规范的点,逐条修改即可。
phpDocument 生成的接口文档的样式中模式会使用 Google 的字体,在国内自然打不开,导致网页打开很慢。找到 D:\zhengxianjun_cdn\www\ran-api\css\template.css,删除第一行的 @import url(https://fonts.googleapis.com/css?family=Source+Sans+Pro);。因为每次生成接口文档都会覆盖 template.css,另一个一劳永逸的办法是在 hosts 文件中加上 127.0.0.1 fonts.googleapis.com
phpDocument 生成的接口文档适配手机网页,但查看不是很便捷。
使用 phpDocument,就需要按照它的规范来抒写代码注释。
phpDocument 代码注释规范:http://www.phpdoc.org/docs/latest/index.html。
支持 28 个标签,有些标签没有完全实现,但实际常用的标签就 10 个左右。
在注释文档中支持部分 html 标签,例如
对应的展示效果如下
想要编写复杂的代码示例仍然不是很容易,但通过注释生成接口文档基本已满足我的需求。
想要细致了解 phpDocument.phar 文件的用法,可以通过 php phar\phpDocumentor.phar –help 命令获得帮助。
示例站点
PHP Ran Framework 的接口文档便是通过 phpDocumentor 创建的 http://ran-api.qiniudn.com
您好,请问一下你这个demo的文档使用的是什么模板呢? 我用默认的模板感觉没有你这个好,能否分享下,谢谢了。
DEMO是另外开发的PHP文档工具生成的,截图是phpDocumentor提供的模板。