PHP读取注释生成api文档

Posted 2020-09-22

总结就是，正则要用的好。

需要生成api的class文件：

<?php
class 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对应的路径。