1.7

mumbaicat · Jul 15, 2018 · 1832b1c · 1832b1c
1 parent a2c9ddc
commit 1832b1c
Show file tree

Hide file tree

Showing 6 changed files with 74 additions and 91 deletions.
diff --git a/README.md b/README.md
@@ -1,12 +1,12 @@
-# php注释自动生成api文档   v1.6
+# php注释自动生成api文档   v1.7
 作者: [Dust](http://dust101.lofter.com)  
 ----
 ```  
-composer require mumbaicat/makeapidoc "1.6"
+composer require mumbaicat/makeapidoc "1.7"
 ```  
 
 ## 注释示例:
-	与普通注释互不影响，要生成记得在第三行开头要有 api 请求方式 url 。  
+	与普通注释互不影响，带有 @method 和 @url 的才会生成  
     注释中备注不要有空格，建议使用标点符号来断句。  
 ```
     /**
@@ -16,30 +16,26 @@ composer require mumbaicat/makeapidoc "1.6"
      * @param integer $limit 每页个数
      * @return integer $code 状态码
      * @return string $msg 返回消息
-     * @return array $void 结果
      */
     public function all($page,$limit){
-    	// 地址中新增两个占位符写法
-    	// api.php/index/{controller}/{method}
-    	// {method} 会自动换成对应的方法名
+    	// 地址中有三个占位符写法
+    	// {url}/api.php/index/{controller}/{action}
+        // {url} 会自动替换成设置的域名 $doc->url = 'xxx'; 来设置。
+    	// {action} 会自动换成对应的方法名
     	// {controller} 会自动换成文件名(大驼峰会转成匈牙利)。
-    	//--------------------------------
+    	// --------------------------------
     	// 默认是文件名和方法名都开启大驼峰转换
     	// 文件名是大写字母出现1次以及以上就转换
     	// 方法名是大写字母出现2次以及以上就转换
-    	// 可以通过下面方法去改变,参数1是文件名,参数2是方法名
-	// $doc->setChange(true,true);
-	// $doc->setTime(1,2);
+        // 可以通过下面方法去改变,参数1是文件名,参数2是方法名
+	    // $doc->setChange(true,true);
+	    // $doc->setTime(1,2);
     }
 
     /**
      * 获取我的列表
      * api GET api.php/index/index/my_list
-     * @param integer $page 页数
-     * @param integer $limit 每页个数
-     * @return integer $code 状态码
-     * @return string $msg 返回消息
-     * @return array 一些数据
+     * @return json json {'code':200,'msg':'json示例'}
      */
     public function my_list($page,$limit){
     	.....
@@ -72,24 +68,15 @@ composer require mumbaicat/makeapidoc "1.6"
 	如果你是Thinkphp5，则将 extend 目录里的 mumbaicat 放在 TP5 的 extend 目录下 。
 
 ### 2.引入
-	// use mumbaicat\apidoc\ApiDoc;    旧版
-    use mumbaicat\makeapidoc\ApiDoc;    // 新版
+    use mumbaicat\makeapidoc\ApiDoc;
 
 ### 3.在合适地方实例化
 	$doc = new ApiDoc('../application');
-	//参数1是代码目录，参数2是保存路径，参数2默认是当前路径。 注意斜杠,windows是/ ，Linux/Mac是\ ，建议使用PHP常常量 DIRECTORY_SEPARATOR
-	$doc->setName('api');
-	//设置项目名称，不写此行默认是api，生成 项目名称.html 的文件，注意保存路径下是否有同名的文件，会被覆盖。
-	$doc->make();
-	//生成 或者 echo $doc->make(true); 生成并返回页面.
-
-### 4.查看文档
-	项目名称.html ,默认是api.html  
+	// 参数1是代码目录，参数2是保存路径，参数2默认是当前路径。 注意斜杠,windows是/ ，Linux/Mac是\ ，建议使用PHP常常量 DIRECTORY_SEPARATOR
+	echo $doc->make();  
 
 ## 将来版本:
- * 在线ajax  
- * 点击URL自动复制  
- * 兼容更低版本的PHP
+ * 等待您的提议 
  * ...  
 
 ## 截图:

diff --git a/extend/mumbaicat/makeapidoc/ApiDoc.php b/extend/mumbaicat/makeapidoc/ApiDoc.php
@@ -4,10 +4,11 @@
 class ApiDoc
 {
 
-    private $mainRegex = '/(\/\*\*.*?\*\sapi.*?\*\/\s*(public|private|protected)?\s*function\s+.*?\s*?\()/s';
+    private $mainRegex = '/(\/\*\*.*?\*\s(api)?.*?\*\/\s*(public|private|protected)?\s*function\s+.*?\s*?\()/s';
     protected $documentPath;
     protected $savePath;
     protected $name = 'api';
+    public $url = 'http://localhost';
     protected $controllerChange = true;
     protected $controllerTimes = 1;
     protected $methodChange = true;
@@ -110,8 +111,7 @@ private function getFileList($path, &$fileList = [], $all = true)
      */
     private function catchEvery($data)
     {
-        preg_match_all($this->mainRegex, $data, $matches);
-        if (empty($matches[1])) {
+        if (!preg_match_all($this->mainRegex, $data, $matches)) {
             return [];
         } else {
             return $matches[1];
@@ -128,20 +128,24 @@ private function parse($data,$fileName)
     {
         $fileName = basename($fileName,'.php');
         $return = [];
-        preg_match_all('/(public|private|protected)?\s*function\s+(.*?)\(/', $data, $matches);
-        $return['funcName'] = !empty($matches[2][0]) ? $matches[2][0] : '[null]';
-        preg_match_all('/\/\*\*\s+\*\s+(.*?)\s+\*\s+api\s+/s', $data, $matches);
-        $return['methodName'] = !empty($matches[1][0]) ? $matches[1][0] : '[null]';
-        preg_match_all('/\s+\*\s+api\s+(.*?)\s+(.*?)\s+(\s+\*\s+@)?.*/', $data, $matches);
-        $return['requestName'] = !empty($matches[1][0]) ? $matches[1][0] : '[null]';
-        $return['requestUrl'] = !empty($matches[2][0]) ? $matches[2][0] : '[null]';
-
+        preg_match_all('/(public|private|protected)?\s*function\s+(?<funcName>.*?)\(/', $data, $matches);
+        $return['funcName'] = !empty($matches['funcName'][0]) ? $matches['funcName'][0] : '[null]';
+        preg_match_all('/\/\*\*\s+\*\s+(?<methodName>.*?)\s+\*/s', $data, $matches);
+        $return['methodName'] = !empty($matches['methodName'][0]) ? $matches['methodName'][0] : '[null]';
+        preg_match_all('/\s+\*\s+\@method\s+(?<requestName>.*)?.*/', $data, $matches);
+        $return['requestName'] = !empty($matches['requestName'][0]) ? $matches['requestName'][0] : '[null]';
+        preg_match_all('/\s+\*\s+\@url\s+(?<requestUrl>.*)?.*/', $data, $matches);
+        $return['requestUrl'] = !empty($matches['requestUrl'][0]) ? $matches['requestUrl'][0] : '[null]';
+        if($return['requestName']=='[null]' and $return['requestUrl']=='[null]'){
+            return false;
+        }
         if($this->controllerChange == true){
             $return['requestUrl'] = str_replace('{controller}',$this->humpToLine($fileName,$this->controllerTimes),$return['requestUrl']);
         }
         if($this->methodChange == true){
-            $return['requestUrl'] = str_replace('{method}',$this->humpToLine($return['funcName'],$this->methodTimes),$return['requestUrl']);
+            $return['requestUrl'] = str_replace('{action}',$this->humpToLine($return['funcName'],$this->methodTimes),$return['requestUrl']);
         }
+        $return['requestUrl'] = str_replace('{url}',$this->url,$return['requestUrl']);
 
         preg_match_all('/\s+\*\s+@param\s+(.*?)\s+(.*?)\s+(.*?)\s/', $data, $matches);
         if(empty($matches[1])){
@@ -184,7 +188,9 @@ private function parse($data,$fileName)
 
             }
         }
+
         return $return;
+
     }
 
     /**
@@ -305,9 +311,9 @@ private function makeRight($rightList){
 
     /**
      * 开始执行生成
-     * @param bool $fetch 是否方法返回,make(true) 可以用来直接输出
+     * @param bool $fetch 是否直接实时输出，默认true，否则生成文件。
      */
-    public function make($fetch=false)
+    public function make($fetch=true)
     {
         $fileList = array();
         $this->getFileList($this->documentPath,$fileList);
@@ -316,13 +322,16 @@ public function make($fetch=false)
         foreach($fileList as $fileName){
             $fileData = file_get_contents($fileName);
             $data = $this->catchEvery($fileData);
+
             foreach ($data as $one) {
                 $infoData = $this->parse($one,$fileName);
-                $rightList[basename($fileName)][] = [
-                    'methodName' => $infoData['methodName'],
-                    'requestUrl' => $infoData['requestUrl'],
-                ];
-                $inputData .= $this->makeTable($infoData);
+                if($infoData != false){
+                    $rightList[basename($fileName)][] = [
+                        'methodName' => $infoData['methodName'],
+                        'requestUrl' => $infoData['requestUrl'],
+                    ];
+                    $inputData .= $this->makeTable($infoData);
+                }
             }
         }
         $tempData = file_get_contents(dirname(__FILE__).DIRECTORY_SEPARATOR.'temp.html');

diff --git a/extend/mumbaicat/makeapidoc/temp.html b/extend/mumbaicat/makeapidoc/temp.html
@@ -70,7 +70,7 @@
     <div class="fly-panel main">
         <div style="margin-bottom:30px;">
             <p style="float:left;">按下 <code>CTRL + F</code> 可以进行搜索。</p>
-            <p style="float:right;">内置Jquery，打开F12可以进行操作。内置request('post','url',data)进行http操作。</p>
+            <p style="float:right;">内置Jquery，打开F12可以进行操作，比如说 $.ajax() 。</p>
         </div>
         <hr style="margin-bottom:20px;clear:both;">
 
@@ -102,16 +102,5 @@
         return false;
     });
 });
-function request(pmethod,purl,pdata=null){
-    $.ajax({
-        type:pmethod,
-        async:false,
-        url:purl,
-        data:pdata,
-        success:function(x){
-            return x;
-        }
-    });
-}
 </script>
 </html>
diff --git a/screenshot/233.gif b/screenshot/233.gif
diff --git a/src/ApiDoc.php b/src/ApiDoc.php
@@ -4,10 +4,11 @@
 class ApiDoc
 {
 
-    private $mainRegex = '/(\/\*\*.*?\*\sapi.*?\*\/\s*(public|private|protected)?\s*function\s+.*?\s*?\()/s';
+    private $mainRegex = '/(\/\*\*.*?\*\s(api)?.*?\*\/\s*(public|private|protected)?\s*function\s+.*?\s*?\()/s';
     protected $documentPath;
     protected $savePath;
     protected $name = 'api';
+    public $url = 'http://localhost';
     protected $controllerChange = true;
     protected $controllerTimes = 1;
     protected $methodChange = true;
@@ -110,8 +111,7 @@ private function getFileList($path, &$fileList = [], $all = true)
      */
     private function catchEvery($data)
     {
-        preg_match_all($this->mainRegex, $data, $matches);
-        if (empty($matches[1])) {
+        if (!preg_match_all($this->mainRegex, $data, $matches)) {
             return [];
         } else {
             return $matches[1];
@@ -128,20 +128,24 @@ private function parse($data,$fileName)
     {
         $fileName = basename($fileName,'.php');
         $return = [];
-        preg_match_all('/(public|private|protected)?\s*function\s+(.*?)\(/', $data, $matches);
-        $return['funcName'] = !empty($matches[2][0]) ? $matches[2][0] : '[null]';
-        preg_match_all('/\/\*\*\s+\*\s+(.*?)\s+\*\s+api\s+/s', $data, $matches);
-        $return['methodName'] = !empty($matches[1][0]) ? $matches[1][0] : '[null]';
-        preg_match_all('/\s+\*\s+api\s+(.*?)\s+(.*?)\s+(\s+\*\s+@)?.*/', $data, $matches);
-        $return['requestName'] = !empty($matches[1][0]) ? $matches[1][0] : '[null]';
-        $return['requestUrl'] = !empty($matches[2][0]) ? $matches[2][0] : '[null]';
-
+        preg_match_all('/(public|private|protected)?\s*function\s+(?<funcName>.*?)\(/', $data, $matches);
+        $return['funcName'] = !empty($matches['funcName'][0]) ? $matches['funcName'][0] : '[null]';
+        preg_match_all('/\/\*\*\s+\*\s+(?<methodName>.*?)\s+\*/s', $data, $matches);
+        $return['methodName'] = !empty($matches['methodName'][0]) ? $matches['methodName'][0] : '[null]';
+        preg_match_all('/\s+\*\s+\@method\s+(?<requestName>.*)?.*/', $data, $matches);
+        $return['requestName'] = !empty($matches['requestName'][0]) ? $matches['requestName'][0] : '[null]';
+        preg_match_all('/\s+\*\s+\@url\s+(?<requestUrl>.*)?.*/', $data, $matches);
+        $return['requestUrl'] = !empty($matches['requestUrl'][0]) ? $matches['requestUrl'][0] : '[null]';
+        if($return['requestName']=='[null]' and $return['requestUrl']=='[null]'){
+            return false;
+        }
         if($this->controllerChange == true){
             $return['requestUrl'] = str_replace('{controller}',$this->humpToLine($fileName,$this->controllerTimes),$return['requestUrl']);
         }
         if($this->methodChange == true){
-            $return['requestUrl'] = str_replace('{method}',$this->humpToLine($return['funcName'],$this->methodTimes),$return['requestUrl']);
+            $return['requestUrl'] = str_replace('{action}',$this->humpToLine($return['funcName'],$this->methodTimes),$return['requestUrl']);
         }
+        $return['requestUrl'] = str_replace('{url}',$this->url,$return['requestUrl']);
 
         preg_match_all('/\s+\*\s+@param\s+(.*?)\s+(.*?)\s+(.*?)\s/', $data, $matches);
         if(empty($matches[1])){
@@ -184,7 +188,9 @@ private function parse($data,$fileName)
 
             }
         }
+
         return $return;
+
     }
 
     /**
@@ -305,9 +311,9 @@ private function makeRight($rightList){
 
     /**
      * 开始执行生成
-     * @param bool $fetch 是否方法返回,make(true) 可以用来直接输出
+     * @param bool $fetch 是否直接实时输出，默认true，否则生成文件。
      */
-    public function make($fetch=false)
+    public function make($fetch=true)
     {
         $fileList = array();
         $this->getFileList($this->documentPath,$fileList);
@@ -316,13 +322,16 @@ public function make($fetch=false)
         foreach($fileList as $fileName){
             $fileData = file_get_contents($fileName);
             $data = $this->catchEvery($fileData);
+
             foreach ($data as $one) {
                 $infoData = $this->parse($one,$fileName);
-                $rightList[basename($fileName)][] = [
-                    'methodName' => $infoData['methodName'],
-                    'requestUrl' => $infoData['requestUrl'],
-                ];
-                $inputData .= $this->makeTable($infoData);
+                if($infoData != false){
+                    $rightList[basename($fileName)][] = [
+                        'methodName' => $infoData['methodName'],
+                        'requestUrl' => $infoData['requestUrl'],
+                    ];
+                    $inputData .= $this->makeTable($infoData);
+                }
             }
         }
         $tempData = file_get_contents(dirname(__FILE__).DIRECTORY_SEPARATOR.'temp.html');

diff --git a/src/temp.html b/src/temp.html
@@ -70,7 +70,7 @@
     <div class="fly-panel main">
         <div style="margin-bottom:30px;">
             <p style="float:left;">按下 <code>CTRL + F</code> 可以进行搜索。</p>
-            <p style="float:right;">内置Jquery，打开F12可以进行操作。内置request('post','url',data)进行http操作。</p>
+            <p style="float:right;">内置Jquery，打开F12可以进行操作，比如说 $.ajax() 。</p>
         </div>
         <hr style="margin-bottom:20px;clear:both;">
 
@@ -102,16 +102,5 @@
         return false;
     });
 });
-function request(pmethod,purl,pdata=null){
-    $.ajax({
-        type:pmethod,
-        async:false,
-        url:purl,
-        data:pdata,
-        success:function(x){
-            return x;
-        }
-    });
-}
 </script>
 </html>