【Laravel實戰】30分鐘學會如何生成 Laravel API 文件
30分鐘學會如何生成 Laravel API 文件
當你辛苦開發完成 API 之後，就必須要撰寫 API 技術文件，這樣的話其他人才知道該怎麼去叫用你的 API
這個工作對大多數開發者來說是非常痛苦且無聊的一件事，因此這篇文章就要教你如何在開發過程中就一邊順手把內容給準備好，等到需要技術文件時，就只需要下一個指令即可輕鬆完成囉
更棒的是，它還是一個非常方便去瀏覽的網頁勒
就讓我來分享 mpociot/laravel-apidoc-generator 套件，它內建已經做好了 apidoc 以及 Laravel 的路徑配置，換言之，它能夠搜尋 Laravel 專案裡頭所有的路由並自動生成專案 API 技術文件網頁，最終達到省去我們自己動手寫的目的！
術語說明
群組
可理解為控制器類別，因為通常一個類別(控制器)就是一個群組
端點
即 API 路由
安裝流程
Step 1. 使用 Composer 套件來進行安裝
開啟 Terminal ，輸入以下指令
composer require --dev mpociot/laravel-apidoc-generator很遺憾，這個套件目前無法順利的支持 Laravel 8 ，所以如果是這個版本在安裝時可能會出現關聯套件版本不相容的錯誤。解決方法請見下方問題排除的Q1：
Step 2.發佈配置檔
開啟 Terminal ，輸入以下指令。將會在 config 資料夾新增一個名為 apidoc.php ，的設定檔。之後我們會需要在這個設定檔裡去加入我們需要的設定
php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-configStep 3.修改配置檔
這一步我們需要編輯 apidoc.php ，建議花點時間看一下每個設定的註解，了解下有哪些設定可以使用，以下我簡單說明比較常用的一些設定
文件格式
如設定為 static 將會生成靜態 html 檔案，無法透過路由來避免訪客進行訪客。如需考慮文件安全性，建議選擇 laravel ，改為生成 Blade 檔案
'type' => 'laravel', //static 或 laravel如選擇 static 的話，文件將生成於 public/docs ，訪問路徑為 http://你的網域/docs ，如選擇 laravel 的話，文件將生成於 resources/views/apidoc/index.blade.php
要生成文件的路由
'routes' => [
[
//須符合以下所有條件的路由才會被寫入 API 文件中，可搭配 * WildCard 使用
'match' => [
//網域
'domains' => [
'*',
// 'domain1.*',
],
//前綴
'prefixes' => [
'/api/auth/*',
],
],
// 白名單，作為未在上面範圍內的補充，可搭配 * WildCard 使用
'include' => [
// 'users.index', 'healthcheck*'
'/api/get-trd'
],
// 黑名單，將在上面範圍的某些路由予以除外，可搭配 * WildCard 使用
'exclude' => [
// 'users.create', 'admin.*'
],
//建立文件時要為這個群組的所有路由加入哪些規則
'apply' => [
//標頭規則
'headers' => [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {token}',
],
],
],
],Logo 圖片
用以替換文件左上角的 Logo 圖片
//請使用絕對路徑，圖片尺寸請使用 230 x 52 pixels
'logo' => public_path('images') . '/logo2.png',預設群組
所有未被納入某個群組的端點，都將被歸類在預設群組，這裡可設定預設群組的顯示文字
'default_group' => '其他',範例程式語言
每個端點都有提供範例程式碼的功能，有支持的包含有 bash . javascript . php 以及 python
'example_languages' => [
'bash',
'javascript',
'php'
],註解撰寫示範
類別檔案的註解寫法範例如下：
/**
* @group 你的群組名稱(必須為唯一)
*
* 你的群組說明
*
* 檔案路徑: app/Http/Controllers/Api/LoginController.php
*
* ```
* (用 ``` 包起來的部分將會被顯示在右方的程式碼區域)
* //只從前端取得 emp_id 和 password 兩個輸入值，回傳陣列
* getCredentials(Request $request)
*
* //指定使用 web Guard
* guard()
* ```
*
*/
class LoginController extends Controller
API端點註解範例如下：
/**
* /get-trd (這裡先寫 API 的 URI)
*
* 端點說明
*
* @authenticated (這個標籤表示此 API 需要完成驗證才能呼叫)
*
* @bodyParam type string required 類型 (表單參數，依序為名稱 型別 必填 說明)
* @bodyParam dorder_ser required
* @bodyParam hcust_id required 會員主鍵
* @urlParam lang The language (路徑參數，依序為名稱 說明)
* @queryParam page The page number to return (查詢字串參數，依序為名稱 說明)
* @queryParam page required The page number. Example: 4 (查詢字串參數帶範例，依序為名稱 必填 說明 範例)
* @queryParam user_id required The id of the user. No-example(查詢字串參數不要帶範例)
*
* @response {(回應範例)
* "id": 4,
* "name": "Jessica Jones",
* "roles": ["admin"]
* }
* @response 404 {(針對某個回應編碼的回應範例)
* "message": "No query results for model [\App\User]"
* }
*
*
* @param Request $request
*
* @return 格式為JSON的回應
*/
public function get_trd(Request $request)針對以上需要的回應範例內容較長時，可將回應範例另外寫在檔案內，比如命名為 user.get.json，放置於 storage/responses 資料夾內，註解可改為如下：
/**
* @responseFile responses/users.get.json
* @responseFile 404 responses/model.not.found.json
*/
public function getUser(int $id)
{
// ...
}針對 Eloquent Resource 端點註解範例如下：
/**
* @apiResourceCollection Mpociot\ApiDoc\Tests\Fixtures\UserResource
* @apiResourceModel Mpociot\ApiDoc\Tests\Fixtures\User
*/
public function listUsers()
{
return UserResource::collection(User::all());
}生成文件
當程式碼的註解都撰寫完畢之後，就可以開始來生成 API 文件了。使用以下命令將會生成文件所需的所有內容，包含 html . css . js 等等
要注意的是每當路由發生改變後，都需要執行以下指令，它將會針對被改動的路由做重新編譯。如果想對如果想對已存在的路由重新再編譯一次的話，可加上
—-force選項
請開啟 Terminal ，輸入以下其中一個指令：
php artisan apidoc:generate
php artisan apidoc:generate --force手動修改文件內容
如果在生成文件之後，在沒有更動路由的情況下，你可以手動去修改生成文件的內容，透過編輯 [index.md](http://index.md) 檔案
這個檔案位於你輸出資料夾內的 source 資料夾內，比如 type 設為 laravel 的話就是在 resources/docs/source/index.md
一旦當你編輯完 Markdown 檔案之後，可使用以下命令來重新打造 API 技術文件
php artisan apidoc:rebuild在文件前後加入額外內容
如果希望在每次執行生成命令(generate)時加上一段固定內容，比如介紹.版權宣言或者是驗證指南等等，你可以透過編輯 source 資料夾內的 prepend.md 和 append.md 檔案來達成此目的
[prepend.md](http://prepend.md) 的內容將會被加在 info 群組裡頭
[append.md](http://append.md) 的內容將會被加在文件的最後
問題排除
Q1.解決 Laravel 8.0 無法安裝的問題
修改 composer.json ，加入以下內容：
//composer.json
"require-dev": {
...
"mpociot/documentarian": "dev-master as 0.4.0",
"mpociot/laravel-apidoc-generator": "dev-master"
},執行 composer update
Q2.點文件左邊的 Group 名稱下方的文字無法順利跳到該區塊
該套件對中文的支持並不高，僅僅只是相容中文顯示而已。不管是文字搜尋或者是連結跳轉都會有問題，因此建議每個方法的註解第一行文字"不要使用中文"，建議格式如下:
/**
* /auth/me 這裡寫端點的Uri，就不會有中文了
*
* 回傳登入者資料
*
* @authenticated
*
* @response {
* "emp_id": "0123456",
* "emp_name": "小明",
* "emp_pd": "123456",
* "gp_name": "admin",
* "emp_type": "1",
* "emp_active": "1",
* "hum_id": "123456",
* "emp_id0": null,
* "user_week": "YYYYYYY",
* "dept_idx": "",
* "muser": "ABC",
* "mdate": "2020-03-01",
* "last_date": "2013-06-24",
* "last_time": null,
* "online": null
* }
*
* @return 以 JSON 形式回傳使用者資料
*/
public function me()
{
return response()->json(auth()->user());
}Q3.訪問文件時出現 Route 未定義的錯誤
這個原因主要是因為你有開啟生成 Postman Collection Json 文件生成功能，但你並未為其加上路由的原因。解決方式只需要到 web.php 加上以下內容
//routes\web.php
use Mpociot\ApiDoc\ApiDoc;
ApiDoc::routes();
