使用 Laravel API 文檔產生器擴充包自動為項目產生 API 文檔

1、簡介&安裝

Laravel API 文檔 產生器 擴充包可以基於 Laravel 應用路由自動產生項目 API 文檔。

我們使用Composer安裝這個擴充包：

$ composer require mpociot/laravel-apidoc-generator

安裝完成後需要到 config/app.php 中註冊服務提供者：

Mpociot\ApiDoc\ApiDocGeneratorServiceProvider::class,

2、使用

基本樣本

下面我們來示範如何使用這個擴充包自動為項目產生API文檔，其原理是通過掃描 routes.php 為指定路由產生相應API文檔，比如我們的路由檔案定義了一個路由如下：

Route::get('api/v1/index', 'ApiController@index');

這個路由對應的控制器方法定義如下：

/** * API首頁 * * 歡迎來到Laravel學院，Laravel學院致力於提供優質Laravel中文學習資源 * */public function index(){}

需要指出的是，Laravel API 產生器通過action方法上的注釋產生 API 相應的描述資訊。我們使用擴充包提供的 api:generate 命令來實現 API 文檔產生：

php artisan api:generate --routePrefix=api/v1/*

該命令的意思是掃描路由中匹配 api/v1/* 的規則並為相應控制器方法產生API文檔，該命令會在 public 目錄下產生一個 docs 目錄以及相應檔案，我們在瀏覽器中通過 http://blog.dev/docs/index.html （我的網域名稱是blog.dev）來查看API文檔：

帶響應資料的樣本

上面是一個最簡單的樣本，大部分時候我們的action會返回HTTP響應，這種情況下API文檔又是如何顯示的呢？

我們在路由檔案 routes.php 中定義一個路由如下：

Route::get('api/v1/test', 'ApiController@test');

對應的控制器方法定義如下：

/** * API響應測試 * * 這是一個API響應測試頁面 * */public function test(){    return new Response('Laravel學院,優質Laravel中文學習資源平台');}

我們在action中簡單返回一個帶字串資訊的Response，要產生該方法的API文檔，還是要運行 api:generate 命令：

php artisan api:generate --routePrefix=api/v1/*

運行完成後，再次訪問 http://blog.dev/docs/index.html ，就可以看到API響應測試資訊：

在右下角我們可以看到響應資料資訊。

如果需要認證使用者才能調用API，可以在產生API文檔的時候加個 --actAsUser 選項並指定使用者ID：

php artisan api:generate --routePrefix=api/v1/* --actAsUserId=1

帶參數的API

下面我們來看一個更加複雜的例子，有時候我們提交POST請求到某個API時會帶參數，這個時候如何產生帶參數的API文檔資訊呢？很簡單，我們只需按照之前的正常邏輯走，然後運行下 api:generate 命令即可。

我們定義一個post請求路由如下：

Route::post('api/v1/params', 'ApiController@params');

在定義應控制器方法之前我們先通過如下命令產生一個請求類：

php artisan make:request TestRequest

這會在 app/Http/Requests 目錄下新產生一個 TestRequest 類，我們編輯該類的 rules 方法如下：

public function rules(){    return [        'title' => 'required|max:255',        'body' => 'required',        'type' => 'in:foo,bar',        'thumbnail' => 'required_if:type,foo|image',    ];}

接下來再去控制器中定義相應方法：

/** * API請求參數 * * 測試API請求參數 * * @param Requests\TestRequest $request */public function params(Requests\TestRequest $request){    }

我們在控制器方法中通過依賴注入傳入我們剛剛建立的 TestRequest 類。

最後還是按部就班，通過 api:generate 命令產生新的API文檔：

php artisan api:generate --routePrefix=api/v1/*

在瀏覽器中訪問 http://blog.dev/docs/index.html ，在頁面中我們可以看到帶參數的API文檔資訊：

更多使用

如果覺得預設的API文件範本太醜陋，該擴充包還提供了 api:update 命令修改預設API文件範本，其操作流程是先修改 index.md 檔案（位於 public/docs/source/index.md ），修改好了之後通過如下命令儲存修改：

php artisan api:update

這個功能很簡單，這裡就不做示範了。瞭解更多請參考該擴充的GitHub項目： https://github.com/mpociot/laravel-apidoc-generator/ 。

