php 在线接口文档,[1.32]-在线接口文档：注释规范 | PhalApi(π框架) - PHP轻量级开源接口框架 - 接口，从简单开始！...

1.32.1 在线接口文档

在线接口文档，主要有两种：

接口列表：用于罗列全部的接口；

接口文档：针对单个接口的文档，用于显示该接口服务的基本信息、接口说明、接口参数、返回结果以及异常情况等。

下面分别进行解释。

1.32.2 接口列表

如何访问接口列表？

在创建一个自己的项目后，可以通过访问对应项目下的listAllApis.php文件来访问接口列表。

具体的URL路径，根据项目的部署情况而定，通常是：

#域名 + 路径 + 项目名 + listAllApis.php

http://localhost/Public/demo/listAllApis.php

接口列表的注释规范

接口列表的注释比较简单，其规范如下：

序号：自动生成，按接口服务名称字典排序后从小到大依次编号

接口服务：自动生成，即service英文接口服务名称

接口名称：接口中文名称，不带任何注解的注释，通常为第一行注释

更多说明：对应@desc 注释，注释内容中不能带有空格

与上面接口列表对应的注释，以User.GetBaseInfo为例，其注释为：

class Api_User extends PhalApi_Api {

/**

* 获取用户基本信息

* @desc 用于获取单个用户基本信息

*/

public function getBaseInfo() {

}

}

结合以上示例，可以看出：

接口服务：由类名Api_User和方法名getBaseInfo组合而成，即：User.GetBaseInfo

接口名称：即：获取用户基本信息

更多说明：对应@desc 注释，即：用于获取单个用户基本信息

1.32.3 接口文档

如何访问接口文档？

在进入接口列表后，点击对应的接口服务即可跳转到对应的接口文档。或者，也可以手动拼接访问。其URL路径与listAllApis.php类似，但需要访问的是checkApiParams.php，通常是：

#域名 + 路径 + 项目名 + checkApiParams.php?service=接口服务

http://localhost/Public/demo/checkApiParams.php?service=User.GetBaseInfo

接口文档的注释规范

接口文档的注释较多，开发人员可在进行项目开发时按需注释。但各部分也很简单明了，如下：

接口服务与接口名称：分别对应上面接口列表中接口服务英文名称和的接口中文名称

接口说明：对应@desc 注释，注释内容中不能带有空格

接口参数：由PhalApi_Api::getRules()中具体接口类定义的接口参数自动生成

返回结果：对应@return 注释，可以有多组，格式为：@return 返回类型 返回字段 说明(不带空格)

异常情况：对应@exception 注释，可以有多组，格式为：@exception 错误码 错误描述信息

温馨提示：@exception 注释需要PhalApi 1.3.6及以上版本

上面示例中，User.GetBaseInfo接口文档对应的注释为：

class Api_User extends PhalApi_Api {

public function getRules() {

return array(

'getMultiBaseInfo' => array(

'userIds' => array('name' => 'user_ids', 'type' => 'array', 'format' => 'explode', 'require' => true, 'desc' => '用户ID，多个以逗号分割'),

),

);

}

/**

* 批量获取用户基本信息

* @desc 用于获取多个用户基本信息

* @return int code 操作码，0表示成功

* @return array list 用户列表

* @return int list[].id 用户ID

* @return string list[].name 用户名字

* @return string list[].note 用户来源

* @return string msg 提示信息

* @exception 400 参数传递错误

* @exception 500 服务器内部错误

*/

public function getMultiBaseInfo() {

}

}

其中，

接口服务与接口名称：由Api_User类名和getMultiBaseInfo方法名生成英文名称，中文名称为不带任何注解的注释：批量获取用户基本信息

接口说明：对应@desc 注释，即：用于获取多个用户基本信息

接口参数：由Api_User::getRules()中定义的接口参数自动生成

返回结果：对应@return 注释，共有6组

异常情况：对应@exception 注释，共有2组

公共的@exception和@return注释

对于当前类函数成员公共的@exception异常情况注释和@return返回结果注释，可在类注释中统一放置。而对于多个类公共的@exception和@return```注释，则可以在父类的类注释中统一放置。

例如，对于上面的Api_User类，可以添加全部函数成员都适用的注释。例如，Api_User类的全部接口都返回code字段，且都返回400和500异常，则可以：

/**

* @return int code 操作码，0表示成功

* @exception 400 参数传递错误

* @exception 500 服务器内部错误

*/

class Api_User extends PhalApi_Api {

这样就不需要在每个函数成员的注释中重复注释。此外，也会依次解析父类中的相关注释。对于相同异常码的@exception注释，子类的注释会覆盖父类的注释，方法的注释会覆盖类的注释；而对于相同的返回结果@return注释，也一样。

温馨提示：公共的@exception和@return注释需要PhalApi 1.4.0及以上版本

1.32.4 生成离线文档

除了使用访问在线文档，也可以生成熟线文档。在命令行，通过CLI方式访问上面的listAllApis.php文件即可生成离线文档到相应的项目目录下。

以Demo项目为例，先执行listAllApis.php脚本生成离线文档。

$ php /path/to/Public/demo/listAllApis.php

生成完毕后，可以看到类似这样的输出：

脚本执行完毕！离线文档保存路径为：/path/to/PhalApi/Public/demo/doc

随后，在浏览器打开并访问：

http://localhost/PhalApi/Public/demo/doc/index.html

便可看到生成好的离线文档了。

自 PhalApi 1.4.1 版本开始，在线接口列表文档有两种主题风格，分别是折叠版和展开版。折叠版是指带有左侧分类菜单的方式，展开版则是一次性罗列全部接口服务，便于搜索。在生成离线文档时，可以通过第二个参数，指定主题风格。如：

生成展开版

$ php /path/to/Public/demo/listAllApis.php expand

生成折叠版

$ php /path/to/Public/demo/listAllApis.php fold

温馨提示：生成离线功能需要 PhalApi 1.4.1 及以上版本支持。