iT邦幫忙

第 12 屆 iThome 鐵人賽

DAY 28
1
自我挑戰組

Laravel 實戰經驗分享系列 第 28

Laravel 實戰經驗分享 - Day28 API 文件的寫法

終於來到倒數的第三篇了,今天來講講如何產生 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,這樣才不會因為規格的臨時變動,又要回去找註解。


上一篇
Laravel 實戰經驗分享 - Day27 Eloquent 的關聯
下一篇
Laravel 實戰經驗分享 - Day29 剩下最後的兩篇,該講些什麼呢?
系列文
Laravel 實戰經驗分享30

1 則留言

0
Rach
iT邦新手 4 級 ‧ 2020-10-13 20:57:19

註解沒寫好,是可以能引起辦公室的殺機

leopan iT邦新手 5 級 ‧ 2020-10-13 21:51:25 檢舉

文章沒寫好也會(哭)

我要留言

立即登入留言