接口返回的类型是html页面_1.10 PhalApi 2.x 接口文档

接口文档

在线接口文档

PhalApi提供一些非常实用而又贴心的功能特性，其中最具特色的就是自动生成的在线可视化文档。在线接口文档主要分为两大类，分别是：

在线接口列表文档
在线接口详情文档

当客户端不知道有哪些接口服务，或者需要查看某个接口服务的说明时，可借助此在线接口文档。访问在线接口列表文档的URL是：

http://dev.phalapi.net/docs.php

打开后，便可看到类似下面这样的在线接口文档。

此在线文档是实时生成的，可根据接口源代码以及注释自动生成。当有新增接口服务时，刷新后便可立即看到效果。通过在接口列表文档，可点击进入相应的接口详情文档页面。

温馨提示：如果打开在线文档，未显示任何接口服务，请确保服务环境是否已关闭PHP的opcache缓存。

代码、注释与接口文档

PhalApi提供了自动生成的在线接口文档，对于每一个接口服务，都有对应的在线接口详情文档。如默认接口服务Site.Index的在线接口详情文档为：

此在线接口详情文档，从上到下，依次说明如下。

接口服务名称

接口服务名称是指用于请求时的名称，对应s参数（或service参数）。接口服务的中文名称，为不带任何注解的注释，通常为接口类成员函数的第一行注释。

class Site extends Api {/*** 默认接口服务*/public function index() {}
}

接口说明

接口说明对应接口类成员函数的@desc注释。

class Site extends Api {/*** 默认接口服务* @desc 默认接口服务，当未指定接口服务时执行此接口服务*/public function index() {}
}

接口参数

接口参数是根据接口类配置的参数规则自动生成，即对应当前接口类getRules()方法中的返回。其中最后的“说明” 字段对应参数规则中的desc选项。可以配置多个参数规则。此外，配置文件./config/app.php中的公共参数规则也会显示在此接口参数里。

class Site extends Api {public function getRules() {return array('index' => array('username'  => array('name' => 'username', 'default' => 'PHPer', ),),);}
}

返回结果

返回结果对应接口类成员函数的@return注释，可以有多组，格式为：@return 返回类型返回字段说明。

class Site extends Api {/*** 默认接口服务* @desc 默认接口服务，当未指定接口服务时执行此接口服务* @return string title 标题* @return string content 内容* @return string version 版本，格式：X.X.X* @return int time 当前时间戳*/public function index() {}
}

接口返回示例

为了方便客户端在未调用接口前也能了解接口的返回格式和示例，可以添加为每个接口服务添加相应的返回示例、同时，考虑到服务端维护的便易性，我们会对每个接口服务单独使用一个文件来存放。默认情况下，返回示例文件存放在：

./src/view/docs/demos

文件名是：

接口服务名称 + .json

例如：

./src/view/docs/demos/App.Site.Index.json

示例文件里可以放置返回给客户端的示例。如：

{"ret": 200,"data": {"title": "Hello PhalApi","version": "2.7.0","time": 1558489902},"msg": ""
}

最后，在线文档的展示效果是：

注意！接口返回示例，需要PhalApi 2.7.0 及以上版本方可支持。

异常情况

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

/*** @exception 400 非法请求，参数传递错误*/public function index() {

刷新后，可以看到新增的异常情况说明。

公共注释

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

也就是说，通过把@exception注解和@return注解移到类注释，可以添加全部函数成员都适用的注解。例如，ApiUser类的全部接口都返回code字段，且都返回400和500异常，则可以：

<?php
namespace AppApi;use PhalApiApi;/*** @return int code 操作码，0表示成功* @exception 400 参数传递错误* @exception 500 服务器内部错误*/class User extends Api {

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

需要注意的是，注释必须是紧挨在类的前面，而不能是在namespace前面，否则会导致注释解析失败。

通过在线接口文档进行测试

在线接口文档，不仅可以用来查看接口文档，包括接口参数、返回字段和功能说明外，还可以在上面进行接口测试。这将会直接请求当前的接口。效果如下：

如何生成离线接口文档？

上面在线的接口文档，也可以一键生成离线版的HTML文档，方便传阅，离线查看。

当需要生成离线文档时，可以在终端，执行以下命令：

phalapi$ php ./public/docs.php Usage:生成展开版：  php ./public/docs.php expand
生成折叠版：  php ./public/docs.php fold脚本执行完毕！离线文档保存路径为：/path/to/phalapi/public/docs

执行后，可以看到类似上面的提示和结果输出。再查看生成的离线文档，可以看到类似有：

phalapi$ tree ./public/docs
./public/docs
├── App.Examples_CURD.Delete.html
├── App.Examples_CURD.Get.html
├── App.Examples_CURD.GetList.html
├── App.Examples_CURD.Insert.html
├── App.Examples_CURD.Update.html
├── App.Examples_Upload.Go.html
├── App.Site.Index.html
└── index.html

最后，可以在页面访问此离线版文档，如访问链接：

http://dev.phalapi.net/docs/index.html

也可以将此docs目录打包，在本地打开访问查看。