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', '[email protected]'); 這個路由對應的控制器方法定義如下：
/**
* 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', '[email protected]'); 對應的控制器方法定義如下：
/**
* 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', '[email protected]'); 在定義應控制器方法之前我們先通過如下指令生成一個請求類：
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/。