您的位置 首页 php

【PHP编程】你还在手写API文档?那你out了!

随着前后端分离思想的盛行,移动端的迅速崛起,编写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框架自动生成在线文档的原理大致这样:

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

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

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

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

  • 在线接口列表文档

  • 在线接口详情文档

PhalApi框架参数规则:

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

  • 一维下标是接口类的方法名,对应接口服务的Action;

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

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

参数规则规定了文档的参数部分,如下:

接口中的设置

文档中的显示

PhalApi框架注释规则:

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

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

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

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

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

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

如何查看在线接口文档

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

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

温馨提示:如果打开在线文档,未显示任何接口服务,请确保服务环境是否已关闭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框架里也可以生成自己的在线接口文档了。


文章来源:智云一二三科技

文章标题:【PHP编程】你还在手写API文档?那你out了!

文章地址:https://www.zhihuclub.com/153007.shtml

关于作者: 智云科技

热门文章

网站地图