1.32.1 在线接口文档

在线接口文档,主要有两种:

  • 接口列表:用于罗列全部的接口;
  • 接口文档:针对单个接口的文档,用于显示该接口服务的基本信息、接口说明、接口参数、返回结果以及异常情况等。
    下面分别进行解释。

1.32.2 接口列表

如何访问接口列表?

创建一个自己的项目后,可以通过访问对应项目下的listAllApis.php文件来访问接口列表。具体的URL路径,根据项目的部署情况而定,通常是:

  1. #域名 + 路径 + 项目名 + listAllApis.php
  2. http://localhost/Public/demo/listAllApis.php

如访问:http://demo.phalapi.net/listAllApis.php,效果如下:[1.32] 在线接口文档:注释规范 - 图1

接口列表的注释规范

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

  • 序号:自动生成,按接口服务名称字典排序后从小到大依次编号
  • 接口服务:自动生成,即service英文接口服务名称
  • 接口名称:接口中文名称,不带任何注解的注释,通常为第一行注释
  • 更多说明:对应@desc 注释,注释内容中不能带有空格
    与上面接口列表对应的注释,以User.GetBaseInfo为例,其注释为:
  1. class Api_User extends PhalApi_Api {
  2. /**
  3. * 获取用户基本信息
  4. * @desc 用于获取单个用户基本信息
  5. */
  6. public function getBaseInfo() {
  7. }
  8. }

结合以上示例,可以看出:

  • 接口服务:由类名Api_User和方法名getBaseInfo组合而成,即:User.GetBaseInfo
  • 接口名称:即:获取用户基本信息
  • 更多说明:对应@desc 注释,即:用于获取单个用户基本信息

    1.32.3 接口文档

如何访问接口文档?

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

  1. #域名 + 路径 + 项目名 + checkApiParams.php?service=接口服务
  2. http://localhost/Public/demo/checkApiParams.php?service=User.GetBaseInfo

如访问:http://demo.phalapi.net/checkApiParams.php?service=User.GetBaseInfo,效果如下:[1.32] 在线接口文档:注释规范 - 图2[1.32] 在线接口文档:注释规范 - 图3

接口文档的注释规范

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

  • 接口服务与接口名称:分别对应上面接口列表中接口服务英文名称和的接口中文名称
  • 接口说明:对应@desc 注释,注释内容中不能带有空格
  • 接口参数:由PhalApi_Api::getRules()中具体接口类定义的接口参数自动生成
  • 返回结果:对应@return 注释,可以有多组,格式为:@return 返回类型 返回字段 说明(不带空格)
  • 异常情况:对应@exception 注释,可以有多组,格式为:@exception 错误码 错误描述信息

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

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

  1. class Api_User extends PhalApi_Api {
  2. public function getRules() {
  3. return array(
  4. 'getMultiBaseInfo' => array(
  5. 'userIds' => array('name' => 'user_ids', 'type' => 'array', 'format' => 'explode', 'require' => true, 'desc' => '用户ID,多个以逗号分割'),
  6. ),
  7. );
  8. }
  9. /**
  10. * 批量获取用户基本信息
  11. * @desc 用于获取多个用户基本信息
  12. * @return int code 操作码,0表示成功
  13. * @return array list 用户列表
  14. * @return int list[].id 用户ID
  15. * @return string list[].name 用户名字
  16. * @return string list[].note 用户来源
  17. * @return string msg 提示信息
  18. * @exception 400 参数传递错误
  19. * @exception 500 服务器内部错误
  20. */
  21. public function getMultiBaseInfo() {
  22. }
  23. }

其中,

  • 接口服务与接口名称:由Api_User类名和getMultiBaseInfo方法名生成英文名称,中文名称为不带任何注解的注释:批量获取用户基本信息
  • 接口说明:对应@desc 注释,即:用于获取多个用户基本信息
  • 接口参数:由Api_User::getRules()中定义的接口参数自动生成
  • 返回结果:对应@return 注释,共有6组
  • 异常情况:对应@exception 注释,共有2组

    @exception@return注释" class="reference-link">公共的@exception@return注释

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

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

  1. <?php
  2. /**
  3. * @return int code 操作码,0表示成功
  4. * @exception 400 参数传递错误
  5. * @exception 500 服务器内部错误
  6. */
  7. class Api_User extends PhalApi_Api {

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

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

1.32.4 生成离线文档

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

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

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

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

  1. 脚本执行完毕!离线文档保存路径为:/path/to/PhalApi/Public/demo/doc

随后,在浏览器打开并访问:

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

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

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

  • 生成展开版
    1. $ php /path/to/Public/demo/listAllApis.php expand
  • 生成折叠版
    1. $ php /path/to/Public/demo/listAllApis.php fold
温馨提示:生成离线功能需要 PhalApi 1.4.1 及以上版本支持。

原文: https://www.phalapi.net/wikis/1-32.html