PHP讀取注釋產生api文檔

標籤：false   file   tmp   oca   web   郵箱驗證   put   ppp   pos   

總結就是，正則要用的好。

需要產生api的class檔案：

<?phpclass emailAction{    /**      * @method 發送郵件      * @url    email/send?token=xxx      * @http  POST      * @param  token              string [必填] 調用介面憑證 (post|get)      * @param  ema_type           enum   [必填] 發送速度：‘普通‘,‘緊急‘,‘延時‘      * @param  ema_from           enum   [必填] 來源：‘B2C‘,‘主站‘,‘客戶網‘,‘CRM‘      * @param  ema_from_email     string [可選] 發送人郵箱      * @param  ema_from_name      string [可選] 發送人      * @param  ema_to_email       string [必填] 接收人手機號碼，多個逗號分隔      * @param  ema_title          string [必填] 標題      * @param  ema_text           string [必填] 內容      * @param  ema_style          string [可選] 資訊類型 例如：郵箱驗證，取回密碼....      * @param  ema_expire_time    int    [可選] 到期時間戳記，超過此時間即使失敗也不再發送      * @author soul      * @copyright 2017/4/13      * @return       {"status":false,"data":‘失敗原因‘,"code":0}      */    function send()    {        $MustArr = [‘ema_type‘, ‘ema_from‘, ‘ema_to_email‘, ‘ema_title‘, ‘ema_text‘];        foreach($MustArr as $V)        {            if(empty($_POST[$V]))            {                echo LibFc::ReturnJson(false, $V.‘參數必填‘);                exit;            }        }$SendEmail = new SendEmail();        $Res = $SendEmail->SendByIds([$Id]);        echo json_encode($Res);    }        /**      * @method 擷取對應ID的資訊      * @http  GET      * @param  token              string [必填] 調用介面憑證 (post|get)      * @param  ema_ids            string   [必填] 郵件ID,使用逗號（,）分隔      * @author soul      * @copyright 2017/4/13      * @return       {"status":false,"data":‘失敗原因‘,"code":0}      */    function get()    {        $Params = mvc::$URL_PARAMS;        if(empty($Params[‘ema_ids‘]))        {            echo LibFc::ReturnJson(false, ‘郵件ID必填‘);            exit;        }        $SmsIdArr = [];        foreach(explode(‘,‘, $Params[‘ema_ids‘]) as $V)        {            $SmsIdArr[] = (int) $V;        }      echo LibFc::ReturnJson(true, $Arr);    }    /**      * @method 發送指定ID的郵件      * @http  POST      * @param  token              string [必填] 調用介面憑證 (post|get)      * @param  ema_ids            array   [必填] 郵件ID      * @author soul      * @copyright 2017/4/13      * @return       {"status":false,"data":‘失敗原因‘,"code":0}      */    function send_by_ids()    {        $Params = mvc::$URL_PARAMS;        if(empty($Params[‘ema_ids‘]))        {            echo LibFc::ReturnJson(false, ‘郵件ID必填‘);            exit;        }        $SendEmail = new SendEmail();        $Res = $SendEmail->SendByIds(explode(‘,‘, $Params[‘ema_ids‘]));        echo json_encode($Res);    }    /**      * @method 刪除對應ID的郵件記錄      * @http  GET      * @param  token              string [必填] 調用介面憑證 (post|get)      * @param  ema_ids            string   [必填] 郵件ID,使用逗號（,）分隔      * @author soul      * @copyright 2017/4/13      * @return {"status":true|false,"data":‘‘,"code":0}      */    function del()    {        $Params = mvc::$URL_PARAMS;        if(empty($Params[‘ema_ids‘]))        {            echo LibFc::ReturnJson(false, ‘郵件ID必填‘);            exit;        }           }}

產生的檔案的代碼：

<?php$url = ‘emailAction.php‘;$c = file_get_contents($url);echo ‘<meta charset="utf-8">‘;$tmp = ‘{t_function}        method         {t_function}        {t_method}    param         {t_param}    return         {t_return}    author         {t_author}    copyright         {t_copyright}‘;$rege = ‘{method (.+)[\s\S]+?author (.+)[\s\S]+?copyright (.+)[\s\S]+?return ([\s\S]+?)\*\/[\s\S]+?function (.+)}‘;preg_match_all($rege, $c, $ms); $m_method    = $ms[1];$m_author    = $ms[2];$m_copyright = $ms[3];$m_return    = $ms[4];$m_function  = $ms[5];echo ‘<pre>‘;$t = ‘‘;foreach($ms[0] as $i => $m){  $t_method   = trim($m_method[$i]);  $t_function = trim($m_function[$i]);  $t_return   = trim($m_return[$i]);  $t_author   = trim($m_author[$i]);  $t_copyright   = trim($m_copyright[$i]);    $t_param = ‘‘;  $rege = ‘{param (.+)}‘;  $rege = ‘{param ([\s\S]+?)\* \@}‘;  if(preg_match_all($rege, $m, $mm)){    $tmpPP = $mm[1];        $t_param = implode("\n        ", $tmpPP);  }   $t.= str_replace(    array(‘{t_method}‘, ‘{t_function}‘, ‘{t_return}‘, ‘{t_author}‘, ‘{t_copyright}‘, ‘{t_param}‘),    array( $t_method ,   $t_function,    $t_return,    $t_author,    $t_copyright,    $t_param),    $tmp  );  $t.=‘-----------------------------------------‘ ."\n";}echo $t;file_put_contents($url.‘.txt‘, $t);

組建檔案的樣子：

這個是最初的版本，實際的情況，對整個項目進行檔案產生api文檔，需要遍曆檔案，產生HTML形式協助文檔的話需要引入模板，並賦予資料：

最終的樣子：

另外：實際開發之中如果注釋嚴格按照PhpDocumentor的文檔要求的規範去注釋的話，是可以直接用PhpDocumentor工具去產生api文檔的，將其代碼下載下來在localhost上可以直接運行，有web頁面去產生協助文檔，web頁面樣本：

官網：

http://pear.php.net/package/PhpDocumentor/

web介面填寫需要產生協助文檔的檔案路徑、輸出的檔案路徑，產生的協助文件範本選擇，如果需要個人化定製，對於源碼很無奈，現在還看不懂，只能對模板變更，需要注意的是，localhost啟動並執行時候需要改動一下phpdoc.bat這個檔案裡面的php.exe對應的路徑。

 

PHP讀取注釋產生api文檔