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，这样才不会因为规格的临时变动，又要回去找注解。