Laravel框架內實現api文件:markdown轉為html
前後端分離的工作模式於今是非常流行了，前後端工作的對接，就離開不了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', 'Admin\ApiDocController@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 App\Http\Controllers\Admin;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
class ApiDocController extends Controller
{
public function showDoc(Request $request){
echo "hello coder";
}
}
瀏覽器輸入http://laraveltest/admin/apidoc,直到出現hello coder後才可以進行後面步驟。
4. 使用外掛實現markdown轉為html
功能很簡單，就直接上程式碼啦。
<?php
namespace App\Http\Controllers\Admin;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
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
一幅如畫卷般的文件頁面就出來嘍。
&n