更多技艺 - [1.32] 在线接口文档：注释规范 - 《PhalApi 1.x 文档》

1.32.1 在线接口文档
1.32.2 接口列表
- 如何访问接口列表？
- 接口列表的注释规范
1.32.3 接口文档
1.32.4 生成离线文档

1.32.1 在线接口文档

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

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

1.32.2 接口列表

如何访问接口列表？

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

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

如访问：http://demo.phalapi.net/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

如访问：http://demo.phalapi.net/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注释" class="reference-link">公共的 @exception和 @return注释

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

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

<?php
/**
 * @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 及以上版本支持。

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

[1.32] 在线接口文档：注释规范