Laravel 自動產生API文件

簡介&安裝

我們打造好的API,沒有使用手冊,對於要介接的開發者,根本無法使用,所以必須提供文件給他們!

所以今天就來介紹 mpociot/laravel-apidoc-generator 這是搭配apidoc + Laravel路徑配置 另外寫好的套件,能夠基於 Laravel 路由自動生成專案 API 文件,可以省掉很多麻煩!

也可以使用 apidoc 官方的套件但就是需要多設定一些路徑!

GitHub連結

使用Composer安裝這個套件

composer require --dev mpociot/laravel-apidoc-generator
安裝情形

使用指令發布配置檔案! (配置檔案可以設定很多東西,例如產生API文件的Logo…)

php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-config

如下圖產生一個 apidoc.php 檔案在 config 資料夾中!

安裝情形

安裝套件及配置檔案都完成後!開始嘗試產生api文件。

如何使用

先下指令看看

執行下方指令,依照我們撰寫的路由產生API文件!會在public目錄下多一個docs目錄以及相關的檔案!

還記得定義API URI 的 api.php 檔案嗎?我們寫的那些程式,對應到的Controller ,在依照每個 Controller 中的方法上方的註解,產生的API檔案。

php artisan apidoc:generate

結果發生錯誤了~~(是因為升級Laravel 6 不相容嗎?讓我們繼續看下去)

發生錯誤

來去發生錯誤的檔案看看,按住 command (ctrl)+點擊上方紅框 發現錯誤地點如下圖! (我使用VScode編輯器,好像現在的編輯器都有這樣的功能,那個路徑應該會出現底線)

發生錯誤2

推測 config 快取未更新 下指令讓他清除 config 快取吧!

php artisan config:clear

在下產生API文件的指令

php artisan apidoc:generate
成功產生檔案

打開 http://127.0.0.1:8000/docs/index.html

API文件畫面

看到左邊的general 分類已經有一排東西!這就是目前專案內的所有API。

開始寫文件

可以注意到文件畫面的又半部深色區域,還會幫我們請求 API 並顯示出 Response 結果,如果需要權限的內容皆顯示

{
    "message": "Unauthenticated."
}

介紹註解關鍵字

@group 幫API分組

@bodyParam 請求時須提供的資料,名稱、生日(選填)、顏色… @queryParam 請求時可附加的參數 排序、篩選…(/api/animals?sort=name:asc) 問候後面的那些參數

@bodyParam @queryParam 可以而外附上 Example: 關鍵字範例

@authenticated 該是否需要身份驗證

@response 返回響應相關。

@responseFile 如果響應資料太多可以用此關鍵字載入 json 檔案

直接附上寫好註解的 AnimalConteoller

<?php

namespace App\Http\Controllers\Api;

use App\Animal;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
use App\Http\Resources\AnimalResource;
use Auth;
use App\Http\Requests\StoreAnimalRequest;
use App\Services\AnimalService;
use App\Http\Controllers\Controller;

/**
 * @group 動物資源
 * 
 * 動物的所有操作
 */
class AnimalController extends Controller
{
    private $animalService;

    public function __construct(AnimalService $animalService)
    {
        $this->animalService = $animalService;
        $this->middleware('auth:api', ['except' => ['index','show']]);
    }

    /**
     * Show Animal List
     * 
     * @queryParam marker 標記由哪個資源開始查詢(預設ID:1) Example: 1
     * @queryParam limit  設定回傳資料筆數(預設10筆資料) Example: 10
     * @queryParam sort   設定排序方式 Example: name:asc
     * 
     * @param \Illuminate\Http\Request $request
     * @return \Illuminate\Http\Response
     */
    public function index(Request $request)
    {
        // 設定預設值

        $marker = isset($request->marker) ? $request->marker : 1;
        $limit = isset($request->limit) ? $request->limit : 10;

        $query = Animal::query();

        $query = $this->animalService->filterAnimals($request->filters, $query);
        
        $query = $this->animalService->sortAnimals($request->sort, $query);

        $animals = $query->where('id', '>=', $marker)->paginate($limit);

        return response($animals, Response::HTTP_OK);
    }

    /**
     * Store Animal
     * 
     * @authenticated
     * 
     * @bodyParam type_id Int required 動物的分類ID(需參照types資料表) Example: 1
     * @bodyParam name String required 動物名稱 Example: 黑熊
     * @bodyParam birthday date required 生日 Example: 2019-10-10
     * @bodyParam area String required 所在區域 Example: 台北市
     * @bodyParam fix boolean required 是否結紮 Example: true
     * @bodyParam description text 簡易描述 Example: 黑狗,胸前有白毛!宛如台灣黑熊
     * @bodyParam personality text 其他介紹 Example: 非常親人!很可愛~
     * 
     * 
     * @param  App\Http\Requests\StoreAnimalRequest  $request
     * @return \Illuminate\Http\Response
     */
    public function store(StoreAnimalRequest $request)
    {
        $animal = Animal::create($request->all());
        return response($animal, Response::HTTP_CREATED);
    }

    /**
     * Show Animal
     *
     * @param  \App\Animal  $animal
     * @return \Illuminate\Http\Response
     */
    public function show(Animal $animal)
    {
        return response(new AnimalResource($animal), Response::HTTP_OK);
    }

    /**
     * Update Animal
     * 
     * @bodyParam type_id Int required 動物的分類ID(需參照types資料表) Example: 1
     * @bodyParam name String required 動物名稱 Example: 黑熊
     * @bodyParam birthday date required 生日 Example: 2019-10-10
     * @bodyParam area String required 所在區域 Example: 台北市
     * @bodyParam fix boolean required 是否結紮 Example: true
     * @bodyParam description text 簡易描述 Example: 黑狗,胸前有白毛!宛如台灣黑熊
     * @bodyParam personality text 其他介紹 Example: 非常親人!很可愛~
     * 
     * @authenticated
     * 
     * @param  \Illuminate\Http\Request  $request
     * @param  \App\Animal  $animal
     * @return \Illuminate\Http\Response
     */
    public function update(Request $request, Animal $animal)
    {
        $animal->update($request->all());
        return response($animal, Response::HTTP_OK);
    }

    /**
     * Delete Animal
     *`
     * @authenticated
     * 
     * @param  \App\Animal  $animal
     * @return \Illuminate\Http\Response
     */
    public function destroy(Animal $animal)
    {
        $animal->delete();
        return response(null, Response::HTTP_NO_CONTENT);
    }

    /**
     * Like/Unlike Animal
     *
     * @authenticated
     * 
     * @param  \App\Animal  $animal
     * @return \Illuminate\Http\Response
     */
    public function like(Animal $animal)
    {
        $animal->like()->toggle(Auth::user()->id);

        return response(null, Response::HTTP_NO_CONTENT);
    }

}

功能很簡單,給上對應的關鍵字就可以囉!但好像沒有比 apidoc 設定來的自由,想要查詢其他關鍵字請參考 laravel-apidoc-generator 官方文件 https://laravel-apidoc-generator.readthedocs.io/en/latest/index.html

記得有修改註解都要下指令產生文件喔!


發佈留言