終於來到倒數的第三篇了，今天來講講如何產生 API 文件，我自己覺得 RESTful API 的缺點在需要完整的文件化，才能有比較清楚的串接方式，偏偏在公司中我又是少數寫 API 的後端工程師，因此寫文件的重責大任自然落到我身上了。

apidoc

mpociot/laravel-apidoc-generator 這個專案是 Laravel 用來自動產生 API 文件的工具。
首先使用 composer 安裝套件

composer require --dev mpociot/laravel-apidoc-generator

發布 config 檔案

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

透過 Artisan 產生 API 文件

php artisan apidoc:generate

預設 url 為 localhost/docs/index.html
基本上這樣就設定完成了，他會幫你產生一個靜態的 html 檔，讓你可以直接檢視。

文件寫法

這個工具是以 Annotation（程式註解）來寫 API，因此我們在每一支 Controller 的函數上面寫這些 API 的規則，再跑一次 php artisan apidoc:generate 就可以更新文件囉！

幾個常用語法

• @group 幫每支 API 分組
• @bodyParam API 請求時要提供的資料
• @queryParam API 請求時可以在後面附加的參數
• @authenticated 該 API 是否需要身分驗證
• @response 返回 response 格式

寫法

/**
 * @response {
 *  "id": 4,
 *  "name": "Jessica Jones",
 *  "roles": ["admin"]
 * }
 */
public function yourfunction() {
    ...
}

其餘語法可參照官方文件

Swagger

Swagger 也是常用來寫 API 文件的工具。

安裝 Swagger 套件

composer require zircote/swagger-php
composer require "darkaonline/l5-swagger:6.*"

clone swagger-ui 並將 ./dist 內的檔案搬到 Laravel 的 Public 資料夾內

git clone https://github.com/swagger-api/swagger-ui
cd ./swagger-ui-master
cp -R ./dist {your-laravel-project-path}/public/{your-api-docs-path}

發布 L5 Swagger

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

於 Controllers 中撰寫 API 規則，並且產生 API 文件 (預設為 JSON 檔)

php artisan l5-swagger:generate

修改 ./dist/index.html 內的 url 請求設定：
(可導到上一步驟產生的 JSON 檔)

window.onload = function() {
    // Begin Swagger UI call region
    const ui = SwaggerUIBundle({
    url: "http://localhost/get-api-document",
    ...
    })
}

文件寫法

Swagger 同樣是使用 Annotation 撰寫 API 規格。

常用語法
需在 Controller 最上面補上 use OpenApi/Annotations

• API information: @Info
• tags: @Tag
• parameters: @Parameter
• responses: @ApiResponse
• requestBody: @RequestBody
• security: @SecurityRequirement
• servers: @Server
• extensions: @Extension
• hidden: @Hidden

其餘語法也可參照官方文件

Swagger 設定相對麻煩，須注意版本為 2.0 或 3.0，兩者語法略有不同易造成錯誤，不過畫面也直覺、漂亮許多，也是目前 API 文件的主流，大家可以依照開發情境選擇自己想用的工具。

用這種 API 文件自動產生的工具還是需要非常注意，註解的維運是很重要的，不要寫完就丟在那了，否則 API 一改，前端爆掉，又沒有最新的文件，你可能會被掐死XD，我自己用這些工具的習慣都還是在專案告一個段落或是穩定後再寫，開發階段都是用共筆文件與前端邊討論規格邊做 API，這樣才不會因為規格的臨時變動，又要回去找註解。