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

時間  2019-11-30
標籤 laravel 框架 實現 api 文檔 markdown 轉爲 html 欄目 Markdown 简体版
原文   原文鏈接

先後端分離的工做模式於今是很是流行了，先後端工做的對接，就離開不了API文檔的輔助。php

 

根據本身以往的工做經歷，以及瞭解的一些資訊，API文檔的創建，無非如下幾種方式：css

1. word文檔模板html

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

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

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

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

 

根據本身的使用心得，發表一下我的見解。json

1.word文檔模板：

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

 

優勢：前期工做少，拿個模板就能夠開寫了。api

缺點：更新接口不是很方便。

 

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

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

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程