前言

最近工作中經常使用到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模板語言，如果在自定義動態模板中應用模板語言，能使我們自定義的動態模板更靈活強大。