文档书写(Document)
概述
用于编写接口文档,通过命令生成,在线的,可测试,可交付的技术文档。
可独立使用
安装
composer require phpzlc/document-bundle
文档配置
-
配置接口主机域名
配置位置
.env.local
配置
DOC_HOST=http://dome-api.com
-
配置文档全局内容
配置位置
src/Document/Config.php
配置项
标题, 出版商, 说明, 注意, 附录。
生成文档
-
命令
php bin/console phpzlc:generate:document
-
生成文件位置
public/apidoc
-
访问文档
{host}/public/apidoc/index.html
-
效果
首页
前要页
数据字典页
接口详情页
Debug页
书写文档
-
书写位置
src/Document
-
工作原理
命令执行之后会扫描 src/Document 下所有后缀为 Document 的类文件中后缀为 Action 的方法。
-
文档目录构建规范
和 src/Controller 下的目录类结构保持一致即可。
-
代码示例
namespace App\Document\Api; use PHPZlc\Document\Document; class ApiDocument extends Document { public function add() { $this->addParam('platform', '平台', 'string', false, 'applets'); return parent::add(); } public function setUrl($url) { return parent::setUrl('/api' . $url); } }
namespace App\Document\Api; class AuthDocument extends ApiDocument { public function add() { $this->setGroup('登录模块'); parent::add(); return $this; } public function setUrl($url) { parent::setUrl('/auth'.$url); return $this; } public function phoneLoginAction() { $this->add() ->setTitle('手机号登录') ->setUrl('/phone-login') ->setMethod('post') ->addParam('phone', '手机号') ->addParam('password', '密码') ->setReturn( <<<EOF <pre> "{ "code": 0, "msg": "登录成功", "msgInfo": [], "data": [] }" "{ "code": 1, "msg": "常规错误", "msgInfo": [], "data": [] }" </pre> EOF ) ->generate(); }