yii2使用注释生成文档

àì夳堔傛蜴生んèń 2022-03-22 11:39 371阅读 0赞

使用yii2已经有一段时间了，在官方的yii2-apidoc没有出来之前一直我们的开发都是使用自己编写的一套模块进行文档输出以及注释规范，于是有了自己写的一套框架，在这里给大家开源出来。

这个插件主要功能：

1、规范API接口的注释。注释即文档，注释结构不对无法渲染出页面，更无法与对接方交流

2、节省前后端文档定义和书写。文档按照基本格式输出，该有的元素都存在，极大的减少前后端交流成本。

3、文档注释方便。配合phpstrom的自定制注释输出，不需要花费额外时间背文档特殊定义词汇。

**准备**

1、请确保yii2开启了url美化功能

'urlManager' = [
    'enablePrettyUrl' = true,
    'showScriptName' = false,
    'rules' =[
    ],
    ]

2、本项目是以module模块的接口开发为基础，请确定项目下有modules模块

3、本项目暂时仅用于yii2-basic项目，暂不适用于yii2高级版

**一、安装**

--------------------

composer require landrain/yii2-apidoc

**二、项目配置：**

--------------------

将下方配置引入入口文件web/index-dev.php或web/index-test.php( 正式环境不要引入）：

$config['modules']['jid'] = [
    'class'=>'landrain\Module',
    'name'=>'接口调试系统',
    'password'=>'123456',
    'ipFilters'=>['*','::1'],
    'language' => 'zh',
    'loginConfig'=>[
    'loginUrl' => '/sail/seller/login',
    'fieldMapping'=>[
    'account'=>'domain',
    'password'=>'password',
    ],
    ],
    'subOfClasses' => [], //需要继承的classes
    'dropdownList' => [
    "android下载" => "https://timgsa.baidu.com/timg?image&quality=80&size=b9999_10000&sec=1547463466873&di=3e5a65b07a4dddf84fce5f421f0b64ca&imgtype=0&src=http%3A%2F%2Fy3.ifengimg.com%2Fnews_spider%2Fdci_2013%2F09%2Fb85234c4801f8b2d7771353867a7a0f8.jpg"
    ], //右上角下拉image
    'xhprofUrl' => 'http://192.168.1.254:8888/xhprof_html/index.php', //xhprofUrl链接
    ];
    
    $config['defaultRoute'] = 'jid';
    if(isset($_REQUEST['xhprof']) && $_REQUEST['xhprof'] == 1){
    xhprof_enable(XHPROF_FLAGS_CPU+XHPROF_FLAGS_MEMORY);
    }

**三、phpstrom注释配置**

打开phpstrom->setting->Editor->File and Code Templates->Includes，将两个文件内容替换原本的文件内容,点击apply即可

1）PHP Function Doc Comment

/**
    #if (${NAME.indexOf('action')} != '-1' &amp;&amp; ${NAME}!='actions')
    @brief 接口名称
    @param type $name this is your test name (=name:defaultValue=)
    @method POST/GET
    @detail 接口描述
    @return array
    @throws Null
    #end
    ${PARAM_DOC}
    #if (${TYPE_HINT} != "void") * @return ${TYPE_HINT}
    #end
    ${THROWS_DOC}
    */

2）PHP Class Doc Comment

/**
    * Class ${NAME}
    #if (${NAMESPACE}) * @package ${NAMESPACE}
    #end
    #if ('Module' == ${NAME})
    @jid-enable
    @jid-name 模块名称
    @jid-id 模块ID
    #elseif (${NAME.indexOf('Controller')}!=-1)
    @brief controller名称
    #end
    */

配置后效果：

![index.gif][]

github项目地址：[https://github.com/FlyLand/yii2-apidoc][https_github.com_FlyLand_yii2-apidoc]

演示项目地址：[http://api.storecardhome.cn/ ][http_api.storecardhome.cn] 演示项目密码：123456

演示项目github源码：  [https://github.com/FlyLand/yii2-apidoc-basic-test][https_github.com_FlyLand_yii2-apidoc-basic-test]

[index.gif]: https://jsinchina.oss-cn-qingdao.aliyuncs.com/flash/index.gif
[https_github.com_FlyLand_yii2-apidoc]: https://github.com/FlyLand/yii2-apidoc
[http_api.storecardhome.cn]: http://api.storecardhome.cn/
[https_github.com_FlyLand_yii2-apidoc-basic-test]: https://github.com/FlyLand/yii2-apidoc-basic-test