网站内容架构,网站设计需要考虑的基本原则,网页界面设计是什么,济南软件开发外包公司接口文档在线接口文档PhalApi提供一些非常实用而又贴心的功能特性#xff0c;其中最具特色的就是自动生成的在线可视化文档。在线接口文档主要分为两大类#xff0c;分别是#xff1a; 在线接口列表文档在线接口详情文档当客户端不知道有哪些接口服务#xff0c;或者需要查…接口文档在线接口文档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目录打包在本地打开访问查看。
