phpDocumentor 使用介绍

开发 PHP 不像开发 Java 有较强的文档注释规范,通过注释可以便捷地生成接口文档。

我在寻找 PHP 接口文档工具时使用过 phpDoc,页面效果不怎么好。辗转使用了 phpDocumentor,页面效果可以接受。

phpDocumentor output

使用 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 source code

对应的展示效果如下

phpDocumentor 效果

想要编写复杂的代码示例仍然不是很容易,但通过注释生成接口文档基本已满足我的需求。

想要细致了解 phpDocument.phar 文件的用法,可以通过 php phar\phpDocumentor.phar –help 命令获得帮助。

示例站点

PHP Ran Framework 的接口文档便是通过 phpDocumentor 创建的 http://ran-api.qiniudn.com

《phpDocumentor 使用介绍》有2个想法

  1. 您好,请问一下你这个demo的文档使用的是什么模板呢? 我用默认的模板感觉没有你这个好,能否分享下,谢谢了。

发表回复

您的电子邮箱地址不会被公开。 必填项已用*标注