Laravel框架內實現api文檔:markdown轉為html

  • 2019 年 10 月 3 日
  • 筆記

前後端分離的工作模式於今是非常流行了，前後端工作的對接，就離開不了API文檔的輔助。

 

根據自己以往的工作經歷，以及了解的一些資訊，API文檔的建立，無非以下幾種方式：

1. word文檔模板

2. 第三方平台，類如postman、showdoc等

3. 框架內單獨自定義一套綁定路由的結構，再解析成html頁面

4. 在框架內每個路由的方法的注釋塊里按照規則寫注釋，再解析生成api文檔

5. 框架內直接編輯markdown文件，再轉換成html頁面

 

根據自己的使用心得，發表一下個人看法。

1.word文檔模板：

這是在第一家公司–富士康科技集團–接觸到的，就是公司準備好了一個API文檔的模板，每個api對應一個表格，在表格里填上對應的路徑(path)，調用方式(method)、請求參數，返回數據結構等資訊。對於剛開始新增api是ok的，當時測試工作和後端正好在不同城市，api文檔可以起到很好的溝通作用。但對於後期維護，總要完善了一個介面，就要對應的去word文檔里查找並修改，一旦後端沒有或忘記更新了，隨著時間過著越久，反而後面越容易把自己帶到坑裡去。

 

優點：前期工作少，拿個模板就可以開寫了。

缺點：更新介面不是很方便。

 

2.第三方平台：

工作經歷中有一家用到，無非就是把api資訊錄入到第三方平台，本人很是反感。尤其是需要像form表單一樣一個個欄位填寫，一個個介面的添加，簡直是作踐後端的時間價值。維護？簡直是更亂，因為第三方平台需要登錄帳號，每多一小步，人發懶的概率就越大，時間久了，api文檔不同步的概率和範圍就更大更廣。

 

工作中現在我一直用postman測試介面，所以postman是必用的工具。至於用它寫api文檔是否支援又是否方便，本人沒有接觸過，就不發表看法了。

showDoc是編輯markdown方式，對於添加API介面，撰寫體驗還是很不錯的。但介面資訊像postman一樣一條條分開的，查找瀏覽不方便，維護一般首先就是要查找，所以維護體驗也感覺很不好。所以以往有的公司，項目涉及到成員多批變遷時，就有那種同一個功能出現幾個不同的api。因為新增介面資訊可以避免去了解去確認此功能介面之前是否已經撰寫過，人都有惰性，就乾脆直接新增了介面文檔記錄，結果就自然導致同樣介面的文檔記錄有兩三條，文檔就慢慢失去了原本的價值：輔助新員工快速了解功能和開展工作。

 

那什麼時候考慮第三方平台呢？

有的第三方平台實現了介面功能實時監控及安全防護，就是有受到攻擊或者介面掛掉的情況時，可以給你手機發簡訊通知你。如果你非常需要這個，那你就用吧。

 

優點：前期工作少，有可能帶有介面安全防護和實時監控，避免因為介面掛掉帶來利益損失。

缺點：不僅多了一步登錄操作，而且大多產品設計的頁面體驗不好，不利於快速新增及更新文檔，管理不好的話，容易失去文檔的本身價值。

 

3.自定義綁定路由的結構：

這是我自己起的名字，可能不太準確。

大體實現方式就是，介面寫好了並定好了路由，就在另外一個php文件針對每一條路由用php語言來定義好一個api文檔所需要的資訊。

例如如下：

$app->route("user/getlist")
    ->request(
        array(
            'page' => '1 //第幾頁',
            'page_size' => '10 //每頁數據條數'
        )
    )
    ->method('post')
    ->response(
        array(
            'data' => array(
                'total_count' => '199 //總記錄條數',
                'list' => array(
                    'username' => 'coderzhai //姓名',
                    'gender' => '1  //1-男 2-女'
                )
            )
        )
    )

然後自己再根據上述結構解析出對應數據展示在頁面里。

 

優點：跟後端程式碼一起，文檔更新及維護更方便。文檔按功能劃分、按區域劃分、按版本劃分、增加用戶許可權控制等實現比較方便。

缺點：由於以上程式碼是用php語言編寫的，一旦遇上哪裡少了括弧或是逗號等php語法錯誤，就會造成文檔頁面無法瀏覽。還需要費時間的去找到問題的所在並及時修復它。介面路由不適宜用resource組合的，因為具體對應增刪查改哪幾個介面不好確定。

 

4.利用方法的注釋塊生成api文檔

這種方式是了解apidoc時了解到的，就是按照規定的規則在介面方法的注釋塊里備註資訊，類如如下：

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

以上是我從網上隨便粘貼的一段，雖說本人寫程式碼不是非常潔癖，但這麼一大串的注釋，本人看著就表示不爽，所以沒一點深入了解它的慾望。不介意的就自行研究嘍。

 

優點：同後端程式碼一起，更新維護距離近在咫尺。

缺點：注釋太大塊了，感覺影響看功能，程式碼顯得十分拖沓，影響美觀。

 

 

5.框架內直接編輯markdown文件

這就是我目前最喜歡的方式，也是本文要講解實現的方式。

 

優點：同後端程式碼一起，維護方便；markdown格式編寫，文檔撰寫省時；所有介面在一個頁面或幾個劃分好的頁面里，方便瀏覽和查找。

缺點：要做一些前期工作來實現。但現在有了現成的插件和本文的教程支援，缺點就可以忽略不計了。

 

 

以上幾種方式都比較完了，現在我就來實現在Laravel內撰寫Api文檔，支援網頁瀏覽。

 

要實現的功能主要就是把指定的md文件轉換成html。

github上有一個人氣很旺的插件：erusev/parsedown, 地址：php解析markdown為html的插件:erusev/parsedown

 

一般項目涉及PC後台，我這裡就新增一個路由文件專門來放這些後台的api。

 

1.安裝erusev/parsedown插件。

編輯composer.json文件，添加程式碼如下：

 "require": {
        "php": "^7.1.3",
        "fideloper/proxy": "^4.0",
        "laravel/framework": "5.7.*",
        "laravel/tinker": "^1.0",
        "erusev/parsedown":"^1.6"  //新增的
    },

 

項目根目錄下執行composer install進行安裝。在vendor文件夾下可看到erusev文件夾，則代表安裝成功。

 

2.在app/Providers/RouteServiceProvider.php中引入自定義的後台路由文件。

public function map()
{
    $this->mapApiRoutes();
    $this->mapWebRoutes();
    //新增的後台路由
    $this->mapAdminRoutes();
}

protected function mapAdminRoutes()
{
    Route::prefix('admin')
    //    ->middleware('api')   //避免篇幅過長，中間件的引入這裡就忽略了
        ->namespace($this->namespace)
        ->group(base_path('routes/admin.php'));
}

 

 

3.添加路由，添加控制器，先調試，要可以成功進入控制器方法。

routes問價下新增admin.php文件，裡面加上我們的api文檔路由：

Route::get('/apidoc', 'AdminApiDocController@showDoc');  //注意後面是反斜杠,否則會報錯

laravel框架入口是public/index.php,為了隱藏這個就自定義個本地解析的名稱，編輯apache的httpd-vhosts文件如下：

<VirtualHost *:80>
	ServerName testlaravel
	DocumentRoot E:/wamp64/www/laravel/public
	<Directory  "E:/wamp64/www/laravel/public/">
		Options +Indexes +Includes +FollowSymLinks +MultiViews
		AllowOverride All
		Allow from all
		Header set Access-Control-Allow-Origin  *
	</Directory>
	RewriteEngine On
	RewriteCond $1 !^(index.php|images|robots.txt)
	RewriteRule ^(.*)$ /index.php/$1 [L]
</VirtualHost>

編輯好後，重啟apache服務。

 

現在來加控制器，laravel可以用artisan命令生成，方便快捷。在項目根目錄執行如下命令：

php artisan make:controller Admin/ApiDocController

接下來編輯controller文件：

<?php

namespace AppHttpControllersAdmin;

use IlluminateHttpRequest;
use AppHttpControllersController;

class ApiDocController extends Controller
{
    public function showDoc(Request $request){
        echo "hello coder";
    }
}

瀏覽器輸入http://laraveltest/admin/apidoc,直到出現hello coder後才可以進行後面步驟。

 

4. 使用插件實現markdown轉為html

功能很簡單，就直接上程式碼啦。

<?php

namespace AppHttpControllersAdmin;

use IlluminateHttpRequest;
use AppHttpControllersController;
use Parsedown;

class ApiDocController extends Controller
{
    public function __construct(){
        $this->markdownParser = new Parsedown();
    }

    public function showDoc(Request $request){
        $fileContent = file_get_contents(storage_path('doc/admin_api.md'));
        $htmlContent = $this->convertMarkdownToHtml($fileContent);
        $content = $this->convertMarkdownToHtml($htmlContent);
        return view('apidoc_admin')->with('content',$content);
    }

    public function convertMarkdownToHtml($markdown)
    {
        $convertedHmtl = $this->markdownParser->setBreaksEnabled(true)->text($markdown);
        return $convertedHmtl;
    }
}

本文推薦的就是用markdown編輯api的方式，md就是markdown文件的後綴，我現在把這個文件放在storage/doc/admin_api.md處。

為了測試，我暫時在文件里粘貼了一個markdown格式的api：

**簡要描述：** 

- 用戶登錄介面

**請求URL：** 
- ` http://xx.com/api/user/login `
  
**請求方式：**
- POST 

**參數：** 

|參數名|必選|類型|說明|
|:----    |:---|:----- |-----   |
|username |是  |string |用戶名   |
|password |是  |string | 密碼    |


 **返回示例**
``` 
  {
    "error_code": 0,
    "data": {
      "uid": "1",
      "username": "zhai coder",
      "name": "翟碼農",
      "groupid": 2 ,
      "reg_time": "2019-08-01",
      "last_login_time": "0",
    }
  }
```
 **返回參數說明** 

|參數名|類型|說明|
|:-----  |:-----|-----                           |
|groupid |int   |用戶組id，1：超級管理員；2：普通用戶  |

 **備註** 

- 更多返回錯誤程式碼請看首頁的錯誤程式碼描述

最後還需要準備好一個view文件。

我是創建在resources/views文件夾下的，文件名為：apidoc_admin.blade.php。

方便表達我強烈的推薦意願，css樣式我都給大家調好了，大家直接拿去用吧。

<!doctype html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Laravel</title>
<style>
    html, body {
        background-color: #fff;
        color: #636b6f;
        font-family: 'Nunito', sans-serif;
        font-weight: 200;
        height: 100vh;
        margin: 0;
        color:#222;  }
    .container{
        width:800px;
        margin:10px auto;
        padding:20px;
        border-left:2px solid silver;
        border-right:2px solid silver; }
    table th,td{
        border:1px solid #ede;
        padding:5px 10px; }
    pre{
        background: #666;
        color: white;
        padding: 20px 10px;
        font-family: yahei;
        overflow: auto; }
    li code{
        font-size: 28px;
        color: #4eb4ee;
        font-weight: bold;
    }
</style>
</head>
<body>
<div class="container">
    {!! $content !!}
</div>
</body>
</html>

 

到這裡，所有工作算是完成了。

在瀏覽器輸入api文檔訪問地址：

http://testlaravel/admin/apidoc

一幅如畫卷般的文檔頁面就出來嘍。

 

VirMach 便宜 VPS

QNews

QNews