在現(xiàn)代 Web 開發(fā)中,清晰、規(guī)范的接口文檔對(duì)于團(tuán)隊(duì)協(xié)作和系統(tǒng)集成至關(guān)重要。php-serialize 是一個(gè)基于 PHP 8.1+ 屬性(Attribute)的序列化庫(kù),它不僅支持對(duì)象與數(shù)組之間的智能轉(zhuǎn)換,還提供了一套強(qiáng)大的 OpenAPI 文檔自動(dòng)生成能力。
本文將帶你快速了解如何使用 php-serialize
的 OpenAPI 功能來(lái)自動(dòng)生成接口文檔,并展示其在實(shí)際開發(fā)中的優(yōu)勢(shì)。
OpenAPI(原 Swagger)是一種開放標(biāo)準(zhǔn),用于描述和文檔化 RESTful API。通過(guò)標(biāo)準(zhǔn)化的格式(如 JSON 或 YAML),開發(fā)者可以清晰地定義接口路徑、請(qǐng)求參數(shù)、響應(yīng)結(jié)構(gòu)以及示例值等信息,從而幫助前后端協(xié)作、測(cè)試自動(dòng)化以及生成客戶端 SDK。
php-serialize
是一個(gè)功能強(qiáng)大的基于屬性(attribute)的 PHP 序列化庫(kù)(需要 PHP ≥ 8.1)。
它允許你將對(duì)象映射為數(shù)組或 JSON,并且可以基于相同的屬性 自動(dòng)生成 OpenAPI 文檔。
?? 統(tǒng)一解決方案,支持 API 數(shù)據(jù)序列化和文檔生成。
composer require astral/serialize
use Astral\Serialize\Serialize;
class UserAddRequest extends Serialize {
public string $name;
public int $id;
}
class UserDetailRequest extends Serialize {
public int $id;
}
use Astral\Serialize\Serialize;
class UserDto extends Serialize {
public string $name,
public int $id;
}
use Astral\Serialize\Serialize;
use Astral\Serialize\OpenApi\Enum\MethodEnum;
#[\Astral\Serialize\OpenApi\Annotations\Tag('用戶模塊管理')]
class UserController {
#[\Astral\Serialize\OpenApi\Annotations\Summary('創(chuàng)建用戶')]
#[\Astral\Serialize\OpenApi\Annotations\Route('/user/create')]
#[\Astral\Serialize\OpenApi\Annotations\RequestBody(UserAddRequest::class)]
#[\Astral\Serialize\OpenApi\Annotations\Response(UserDto::class)]
public function create()
{
return new UserDto();
}
#[\Astral\Serialize\OpenApi\Annotations\Summary('用戶詳情')]
#[\Astral\Serialize\OpenApi\Annotations\Route(route:'/user/detail', method: MethodEnum::GET)]
public function detail(UserDetailRequest $request): UserDto
{
return new UserDto();
}
}
進(jìn)入項(xiàng)目根目錄
docker run -v $PWD/vendor/astral/php-serialize/src/OpenApi/Frankenphp/Caddyfile:/etc/frankenphp/Caddyfile -v $PWD:/app -p 8089:80 dunglas/frankenphp
訪問(wèn) http://127.0.0.1:8089
查看Json文檔
訪問(wèn) http://127.0.0.1:8089/docs
查看UI文檔
php-serialize
提供了一種優(yōu)雅的方式來(lái)實(shí)現(xiàn) API 數(shù)據(jù)序列化與文檔自動(dòng)生成,具有以下優(yōu)勢(shì):
如果你正在尋找一個(gè)輕量級(jí)但功能強(qiáng)大的 API 文檔生成方案,不妨試試 php-serialize
!
不錯(cuò)