安裝配置
安裝完該擴充包後，将配置檔案
apidoc.php
釋出到
config
目錄下，如果要為 Dingo API 生成文檔，需要将該配置檔案中的
router
配置項修改為
dingo
(預設是
laravel
，用于為 Laravel 路由生成接口文檔)，更多配置項的配置可以浏覽該配置檔案檢視，每個配置都有完整的注釋，你也可以檢視官方文檔去了解。
由于我們定義 Dingo API 時，設定了 v1、v2、v3 三個版本，是以我們将
routes
配置項中的
version
配置調整為支援所有版本：
'versions' => [
'v1',
'v2',
'v3'
],
通過注解對 API 進行描述
和 Dingo 自帶的 API 文檔生成功能一樣，API 文檔生成器擴充包也是通過注解對 API 接口進行描述，然後運作 Artisan 指令根據這些注解資訊生成對應的 API 文檔，同樣，該功能隻支援通過控制器定義的 API 路由。
接下來我們修改
Api\TaskController
的注解資訊如下：
...
class TaskController extends ApiController
{
public function __construct()
{
$this->middleware('auth:api');
}
public function index(Request $request)
{
$limit = $request->input('limit') ? : 10;
// 擷取認證使用者執行個體
$user = $request->user('api');
$tasks = Task::where('user_id', $user->id)->paginate($limit);
return $this->response->paginator($tasks, new TaskTransformer());
}
public function store(CreateTaskRequest $request)
{
$request->validate([
'text' => 'required|string'
]);
$task = Task::create([
'text' => $request->post('text'),
'user_id' => auth('api')->user()->id,
'is_completed' => Task::NOT_COMPLETED
]);
return $this->response->item($task, new TaskTransformer());
}
public function show($id)
{
$task = Task::findOrFail($id);
return $this->response->item($task, new TaskTransformer());
}
public function update(Request $request, $id)
{
$task = Task::findOrFail($id);
$updatedTask = tap($task)->update(request()->only(['is_completed', 'text']))->fresh();
return $this->response->item($updatedTask, new TaskTransformer());
}
public function destroy($id)
{
$task = Task::findOrFail($id);
$task->delete();
return response()->json(['message' => 'Task deleted'], 200);
}
}
我們可以對比着上篇教程 Dingo API 内置的注解指令來看：
-
@group
-
@authenticated
-
@queryParam
-
@bodyParam
-
@response
此外，還可以通過
@responseFile
從檔案中擷取傳回的示例響應資料，這些儲存示例資料的檔案位于
storage/responses
目錄下(通常是 JSON 檔案)，需要我們自己去建立并儲存：
這樣做的好處是對于複雜響應資料，可以避免控制器注解變得冗長，此外，如果多個 API 傳回的資料格式相同，還可以實作示例資料的複用。
關于 API 文檔生成器擴充包支援的注解指令我們就簡單介紹到這裡，更多使用方式可以參考官方文檔。
生成 API 文檔
為所有 Dingo 路由控制器設定好注解之後，就可以運作 API 文檔生成器擴充包提供的
apidoc:generate
指令為 Dingo API 生成文檔了：
php artisan apidoc:generate
該擴充包同樣會跳過通過匿名函數定義的路由，隻為通過控制器定義的 API 路由生成文檔：
API 文檔預設會生成到
public/docs
目錄，是以我們可以在浏覽器中通過
http://todo.test/docs/index.html
直接通路：
我們可以通過點選左側的菜單快速在不同的接口文檔之間切換(注意對應的控制器方法注釋要包含英文字元，否則建立錨點的時候會失敗，導緻點選切換失效)。
此外，在
public/docs
目錄下，還可以看到預設生成的
collection.json
檔案，你可以将該檔案導入到 Postman 裡面以快速實作 API 接口的測試和使用：
如果是要為 Laravel API 生成文檔，将
apidoc.php
配置檔案中的
router
切換回
laravel
，注解定義方式完全一樣，然後通過文檔生成指令生成對應的 API 文檔，這裡就不再單獨介紹了。
來源：https://laravelacademy.org/post/19689.html
以上内容希望幫助到大家，有需要的可以添加下方二維碼進群交流學習PHP中進階技術。
如果你想和PHP大神交流加微信，拉你入群
如果你想獲得學習資料加微信，送你資源
掃碼關注菲菲
php實戰資源免費送
COME BABY