开发接口文档--本接口文档是读取控制器方法上的注释自动生成的
Posted 邹柯
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了开发接口文档--本接口文档是读取控制器方法上的注释自动生成的相关的知识，希望对你有一定的参考价值。
示例:www.zouke1220.xyz
本文档是参考网上的然后根据公司需要对代码进行了抽取和优化（主要是加了标题栏和对输出进行了格式化输出，更换了页面渲染方式（改为直接使用php进行渲染，原来的是使用了模板引擎），可读性较好），配置简单，读取方便，和项目耦合性较小，只需要将api_view这个文件夹放到和项目同级就可以使用，接口文档只有100多k大小
一.apiview目录结构说明
二.读取注释自动生成api接口文档和api接口调试
1.控制器上的注释写法
按照下图格式写接口方法注释（主是在控制器上面和方法上）
2.写读控制器方法注释的方法
common.php
<?php //@class 得到类标题 function get_class_title($str){ $target = \'/@class\\s(.*)\\s/\'; $res = preg_match($target,$str,$result); if($res == 1){ return $result[1]; } } //@title 得到方法标题 function get_title($str){ $target = \'/@title\\s(.*)\\s/\'; $res = preg_match($target,$str,$result); if($res == 1){ return $result[1]; } } //@param age 否 int 年龄参数的说明 function get_param($str){ $target = \'/@param\\s(.*)\\s/\'; $res = preg_match_all($target,$str,$result); if($res){ $new_result = array(); foreach($result[1] as $k=>$v){ $new_array = explode(\' \',$v);//print_r($new_array); if(is_array($new_array) && !empty($new_array)){ $new_result[] = $new_array; } } return $new_result; } } //@return 返回数据实例 function get_return($str){ $target = \'/@return\\s(.*)\\s/\'; $res = preg_match($target,$str,$result); if($res == 1){ return $result[1]; } } //@return_param_explain 返回数据说明 function get_return_param_explain($str){ $target = \'/@return_param_explain\\s(.*)\\s/\'; $res = preg_match($target,$str,$result); if($res){ $new_result = array(); $new_array = explode(\' \',trim($result[1])); foreach($new_array as $k=>$v){ if($v==null){ unset($new_array[$k]); } } if(is_array($new_array) && !empty($new_array)){ $new_result[] = $new_array; } return $new_result; } } //@example 调用示例 function get_example($str){ $target = \'/@example\\s(.*)\\s/\'; $res = preg_match($target,$str,$result); if($res == 1){ return $result[1]; } } //@method POST function get_method($str){ $target = \'/@method\\s(.*)\\s/\'; $res = preg_match($target,$str,$result); if($res == 1){ return $result[1]; } } //@author 开发者 function get_author($str){ $target = \'/@author\\s(.*)\\s/\'; $res = preg_match($target,$str,$result); if($res == 1){ return $result[1]; } } //组装数据 function parsing($str){ $target = \'/\\/\\*[\\s\\S]*?\\*\\//\'; $res = preg_match_all($target,$str,$result); if($res){ $new_result = array(); foreach($result[0] as $k=>$v){ if($k == 0){ $new_result[\'title\'] = get_class_title($v); }else{ $example=get_example($v); $new_result[\'api\'][$k][\'title\'] = get_title($v); $new_result[\'api\'][$k][\'param\'] = get_param($v); $new_result[\'api\'][$k][\'return\']= get_return($v); $new_result[\'api\'][$k][\'return_param_explain\']=get_return_param_explain($v); $new_result[\'api\'][$k][\'example\']= $example; $new_result[\'api\'][$k][\'method\'] = get_method($v); $new_result[\'api\'][$k][\'author\'] = get_author($v); $in=stripos($example,"/"); $in2=stripos($example,"?"); $controller=substr($example,0,$in); $action=substr($example,$in+1,$in2-$in-1); $new_result[\'api\'][$k][\'controller\']=strtolower($controller); $new_result[\'api\'][$k][\'action\']=$action; } } return $new_result; } }
3.将接口文档放置在和项目同级(当然了也可以不同级)
三.配置文件修改
config.php
<?php $conf=array( \'app\'=>array(\'url\'=>\'/webApp/Application/Webapp/Controller/*.php\',\'title\'=>\'APP\',\'domain\'=>\'app.zouke.com\'), \'h5\'=>array(\'url\'=>\'/wg/Application/Apph5/Controller/*.php\',\'title\'=>\'H5\',\'domain\'=>\'h5.zouke.com\'), \'manage\'=>array(\'url\'=>\'/manage/Application/Fmall_cloud/Controller/*.php\',\'title\'=>\'管理后台\',\'domain\'=>\'fenglei_manage.com\'), \'inner_open\'=>array(\'url\'=>\'/inner_open/Application/Inner/Model/*.php\',\'title\'=>\'java调php接口\',\'domain\'=>\'inner.test.feelee.cc\'), );
上述配置文件的配置应该配置自己本地真实的配置，url为项目控制器所在的文件，这里有4个项目
注：domain域名前不要加http://
四.api接口文档效果图-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
上面的返回结果实例要格式化输出，在index.php里引入格式化文件jsonFormat.php，在index.html调用格式化函数
jsonFormat.php
<?php /** Json数据格式化 * @param Mixed $json 数据 * @return JSON */ function format_json($json, $html = false) { $tabcount = 0; $result = \'\'; $inquote = false; $ignorenext = false; if ($html) { $tab = " "; $newline = "<br/>"; } else { $tab = "\\t"; $newline = "\\n"; } for($i = 0; $i < strlen($json); $i++) { $char = $json[$i]; if ($ignorenext) { $result .= $char; $ignorenext = false; } else { switch($char) { case \'{\': $tabcount++; $result .= $char . $newline . str_repeat($tab, $tabcount); break; case \'}\': $tabcount--; $result = trim($result) . $newline . str_repeat($tab, $tabcount) . $char; break; case \',\': $result .= $char . $newline . str_repeat($tab, $tabcount); break; case \'"\': $inquote = !$inquote; $result .= $char; break; case \'\\\\\': if ($inquote) $ignorenext = true; $result .= $char; break; default: $result .= $char; } } } return $result; }
index.html
<!DOCTYPE html> <html lang="zh-CN" dir="ltr" class="client-nojs"> <head> <meta charset="UTF-8" /> <title>开发者接口文档</title> <meta http-equiv="X-UA-Compatible" content="IE=EDGE" /> <link rel="stylesheet" href="./view/front/css/load.css" /> <style> a:lang(ar),a:lang(kk-arab),a:lang(mzn),a:lang(ps),a:lang(ur){text-decoration:none} table { border-collapse: collapse; border-spacing: 0; width: 99%; border: 1px solid #b5c5da; border-top: 3px solid #b5c5da; margin: 10px 10px; } tbody { display: table-row-group; vertical-align: middle; border-color: inherit; } .grayBlueBg { background: #f4f4f5; } tr { display: table-row; vertical-align: inherit; border-color: inherit; } td { height: 30px; line-height: 30px; border: 1px solid #b5c5da; text-align: center; } th { border: none; border-right: 1px solid #b5c5da; } </style> </head> <body class="mediawiki ltr sitedir-ltr ns-0 ns-subject skin-vector action-view vector-animateLayout"> <!-- header --> <div class="headWrap"> <div class="header" id="header"> <div class="inner" style="width: 1270px;"> <a class="logo" href="javascript:;" style="font-size: 26px;margin-right:200px;">API接口文档</a> <?php $i=0; $cn=count($conf); foreach($conf as $k=>$v){ $i++; ?> <a class="<?php echo $k?>" href="?par=<?php echo $k?>" style="font-size: 20px;"><?php echo $v[\'title\']?></a> <?php if($i != $cn) echo " | ";?> <?php } ?> <a class="" href="index.php?par=<?php echo $params?>" style="font-size: 20px;;margin-left:100px;">API接口调试</a> <a class="" href="log.php?par=<?php echo $params?>" style="font-size: 20px;;margin-left:20px;">log记录</a> </div> </div> </div> <!-- main content container --> <div class="mainwrapper" style="width: 1270px;"> <div class="inner"> <div id="content" class="mw-body scroll-bar-wrap" role="main"> <?php foreach($data as $k=>$v){ if(!empty($v[\'api\'])){ foreach($v[\'api\'] as $k2=>$v2){ if($k == 1 || $k2 == 1){ ?> <div class="scroll-box content_data" id="content_<?php echo $k?>_<?php echo $k2?>" style="display: none"> <?php }else{ ?> <div class="scroll-box content_data" id="content_<?php echo $k?>_<?php echo $k2?>"> <?php }?> <a id="top"></a> <div id="mw-js-message" style="display:none;"></div> <div class="content_hd"> <h2 id="firstHeading" class="firstHeading" style="width:100%;"><?php echo $v2[\'title\']." 开发者：".$v2[\'author\'];?></h2> </div> <div id="bodyContent" class="bodyContent"> <div id="mw-content-text" lang="zh-CN" dir="ltr" class="mw-content-ltr"> <ul><li>请求方式</li></ul> <pre><?php echo $v2[\'method\']?></pre> <ul><li>请求示例 <a href="index.php?par=<?php echo $params?>&controller=<?php echo $v2[\'controller\']?>&action=<?php echo $v2[\'action\']?>">去调试</a></li></ul> <pre><?php echo $conf[$params][\'domain\']."/".$v2[\'example\']?></pre> <ul><li>接收参数说明</li></ul> <table border="1" cellspacing="0" cellpadding="3" align="center" width="640px"> <tr class="grayBlueBg"> <th>参数</th> <th>是否必须</th> <th>类型</th> <th>说明</th> </tr> <?php if(!empty($v2[\'param\'])){ foreach($v2[\'param\'] as $k3=>$v3){ if($k3 % 2 == 0){ ?> <tr class="grayBlueBg"> <?php }else{?> <tr> <?php }?> <td align="center"><?php echo $v3[0]?></td> <td align="center"><?php echo $v3[1]?></td> <td align="center"><?php echo $v3[2]?></td> <td align="center"><?php echo $v3[3]?></td> </tr> <?php } } ?> </table> <ul> <li>返回结果实例</li> </ul> <pre id="return" readonly="readonly"> <?php echo "<br>"; if(empty($v2[\'return\'])){ if(!empty($res_info)){ echo format_json($res_info[$v2[\'controller\'].\'/\'.$v2[\'action\']]); } } else { echo format_json($v2[\'return\']); } echo "<br>"; ?> </pre> <ul> <li>返回参数说明</li> </ul> <pre> <?php if(!empty($v2[\'return_param_explain\'][0])){ foreach($v2[\'return_param_explain\'][0] as $k3=>$v3){ echo "<br>".$v3."<br>"; } }else{ echo "<br>无<br>"; } ?> </pre> </div> <div id=\'catlinks\' class=\'catlinks catlinks-allhidden\'></div> <div class="visualClear"></div> </div> </div> <?php } } } ?> </div> <!-- nav --> <div id="mw-panel" class="collapsible-nav scroll-bar-wrap"> <div class="scroll-box"> <div class="portal" > <h5 class="category separator">API_<?php echo $title;?></h5> </div> <?php foreach($data as $k=>$v){?> <div class="portal" role="navigation" > <h5><span class="portal_arrow"></span><?php echo $v[\'title\']?></h5> <div class="body" > <ul> <?php if(!empty($v[\'api\'])){ foreach($v[\'api\'] as $k2=>$v2){ ?> <li ><a data-id="<?php echo $k?>_<?php echo $k2?>" title="<?php echo $v2[\'title\']?>" class="item" href="JavaScript:;"><?php echo $v2[\'title\']?></a></li> <?php } }else{ ?> <li><a data-id="0_0" class="item" href="JavaScript:;"></a></li> <?php } ?> </ul> </div> </div> <?php }?> </div> <div class="cover-bar"></div> </div> </div> </div> <!-- footer --> <div id="footer" role="contentinfo" class="footer"> <p class="copyright">Copyright @ 2017 邹柯. All Rights Reserved.</p> </div> <script type="text/javascript" src=\'./view/front/js/jquery-min.js\'></script> <script type="text/javascript" src=\'./view/front/js/wiki.js\'></script> <script> var type = GetQueryString(\'par\'); $(function(){ $(\'.\'+type).css(\'color\',\'black\'); $(\'.\'+type).css(\'background-color\',\'#EAEAEA\'); }); $(\'.item\').click(function(){ var id = $(this).data(\'id\'); $(\'.content_data\').hide(); $(\'#content_\'+id).show(); }); function GetQueryString(name){ var reg = new RegExp("(^|&)"+ name +"=([^&]*)(&|$)"); var r = window.location.search.substr(1).match(reg); if(r!=null)return unescape(r[2]); return null; } </script> </body> </html>
apiview.php
<?php define(\'ACC\',true); header(\'content-type:text/html;charset=utf-8Java文档注释APIAuto：敏捷开发最强大易用的 HTTP 接口工具，机器学习零代码测试生成代码与静态检查生成文档与光标悬浮注释，集 文档测试Mock调试管理 于一体的一站式体验。