phpstrom中自定义Live Templates支持apidoc文档注释

前言

最近工作中经常使用到apidoc生成web api文档，代码中写apidoc的注释结构还是比较痛苦的，没有提示纯手敲，忘记一些结构还得去翻apidoc的文档，很痛苦的有木有……
后来我就在想，是否可以把apidoc的注释语法结构定义到phpstrom中，只需要简单快捷键或者命令，直接输出apidoc注释的完整结构。

什么是apidoc？

apiDoc creates a documentation from API annotations in your source code.
官方文档

上面的官方文档中的一句话：apidoc 在源代码中创建了一个API注释的文档。apidoc是nodejs开发的，编写好注释文档后，一条命令即可生成html接口文档。

如何定义Live Templates？

1. 打开Live Templates自定义的设置界面：File>Settings>Editor>Live Templates，
   
2. 新增一个分组PHP DOC
3. 新增一个动态模板acc，我们可以将我们预期的自动补全注释结构编辑到模板当中，我这里直接放了一个完整的apidoc示例

/**
 * @api {post | get} /module/controller/action 名称
 * @apiGroup 分组名称
 * @apiName 名称
 * @apiVersion 1.0.0
 *
 * @apiDescription 接口描述
 *
 * @apiParam {String} $param1  参数说明
 *
 * @apiSuccess {Number} code    状态码，0：请求成功
 * @apiSuccess {String} message   提示信息
 * @apiSuccess {Object} data    返回数据
 *
 * @apiSuccessExample {json} Success-Response:
 * {"code":0,"message":"","data":[]}
 *
 * @apiErrorExample {json} Error-Response:
 * {"code":5001,"message":"接口异常"}
 *
 */
public function $NAME$($PARAMETERS$){
    $END$
}

4. 保存后，可以到编译器中试验一下，直接输入acc即有提示，按下Tab键自动补全。

总结

上面更多的只是展示了自定义方法，咱们具体设置的时候就灵活很多了，可以根据需要把apiParam、apiSucess等这些分布拆成独立的模板，需要的时候根据不同的指令快速输出想要的注释结构。
jetbrains 家族的开发工具，都使用的是Apache Velocity模板语言，如果在自定义动态模板中应用模板语言，能使我们自定义的动态模板更灵活强大。