随着前后端分离思想的盛行，移动端的迅速崛起，编写API的需求也来越多，如何编写出更加规范的API文档说明，可以说显的尤为重要。可能以前你是通过手写的方式来生成和编写这些文档，但是以后你可以不用这么做了。本文下面要分享的这个框架——PhalApi框架，可以自动生成API文档，无须手动维护。

什么是PhalApi框架？

PhalApi框架是一个PHP轻量级开源接口框架，致力于快速开发接口服务。支持HTTP/SOAP/RPC等协议，可用于搭建接口/微服务/RESTful接口/Web Services。

PhalApi框架目前的最新版本是PhalApi 2.1.2，支持PHP 5.3及以上版本，并支持PHP 7。

PhalApi框架的特色

1、轻量

PhalApi框架由于是一个致力于快速开发接口服务的框架，因此，相对于ThinkPHP、Laravel、Yii……等框架，它更量。没有太多无关紧要的内容。

2、自动生成在线接口文档

我觉得这是该框架最大的特色，我之所以喜欢这个框架，很大程度上也在于这一点。我写这篇文章的唯一目的，也是想介绍下接口文档自动生成功能。

如何自动生成在线接口文档

PhalApi框架自动生成在线文档的原理大致这样：

编写接口时，根据注释规则，使用文档注释，对每个接口类和及其方法进行注释说明

通过PHP反射机制，获取接口类文件及其方法文档注释。

根据注释规则，对获取的文档注释，进行操作，提取内容，并显示出来

PhalApi框架自动生成的在线文档主要有两类：

在线接口列表文档

在线接口详情文档

PhalApi框架参数规则：

参数规则是针对各个接口服务而配置的多维规则数组，由接口类的getRules()方法返回。其中，

一维下标是接口类的方法名，对应接口服务的Action；

二维下标是类属性名称，对应在服务端获取通过验证和转换化的最终客户端参数；

三维下标name是接口参数名称，对应外部客户端请求时需要提供的参数名称。

参数规则规定了文档的参数部分，如下：

接口中的设置

文档中的显示

PhalApi框架注释规则：

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

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

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

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

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

对于当前类的全部函数成员的公共@exception异常情况注释和@return返回结果注释，可在类注释中统一放置。而对于多个类公共的@exception和@return```注释，则可以在父类的类注释中统一放置。也就是说，通过把@exception注解和@return注解移到类注释，可以添加全部函数成员都适用的注解

如何查看在线接口文档

按框架指定的格式完成接口代码编写后，PhalApi会自动生成在线接口列表文档和在线接口详情文档，以方便客户端实时查看最新的接口签名和返回字段。

当项目搭建成功后，直接访问如下链接，即可查看在线文档：

http://你的域名/docs.php

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

如何查看离线接口文档

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

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

如何将在线接口文档移植到其他程序

PhalApi框架在线接口文档生成程序虽然嵌在了PhalApi框架中，但是也不是不可以独立于PhalApi框架之外。下面以ThinkPHP5.0为例，简要说明如何将这一功能移植到其他项目里。

1、在项目application目录同一级，创建一个文档程序运行目录doc，并将PhalApi框架里的config、public、vendor、src目录，复制到doc目录，如下：

2、将doc/public目录下的docs.php文件移到项目的public目录下

3、按如下方式，修改docs.php文件

4、按如下方式，修改doc/public/init.php文件

5、按如下方式，修改doc/verdor/phalapi/kernal/src/Helper/ApiList.php

6、按如下方式，修改doc/verdor/phalapi/kernal/src/Helper/ApiDesc.php

7、按如下方式，修改doc/verdor/phalapi/kernal/src/ApiFactory.php

8、在doc/config目录增加api.php配置文件，指定接口服务目录。

9、每个接口服务类都要继承\PhalApi\Api，如下：

接口服务目录public/index.php

至此，PhalApi框架在线接口文档生成程序，就移植到ThinkPHP5.0框架了，你在ThinkPHP5.0框架里也可以生成自己的在线接口文档了。