使用 php-serialize 自動(dòng)生成 OpenAPI 文檔：高效構(gòu)建 API 接口文檔的利器

在現(xiàn)代 Web 開發(fā)中，清晰、規(guī)范的接口文檔對于團(tuán)隊(duì)協(xié)作和系統(tǒng)集成至關(guān)重要。php-serialize 是一個(gè)基于 PHP 8.1+ 屬性（Attribute）的序列化庫，它不僅支持對象與數(shù)組之間的智能轉(zhuǎn)換，還提供了一套強(qiáng)大的 OpenAPI 文檔自動(dòng)生成能力。

本文將帶你快速了解如何使用 php-serialize 的 OpenAPI 功能來自動(dòng)生成接口文檔，并展示其在實(shí)際開發(fā)中的優(yōu)勢。

php-serialize：https://github.com/astral-data/php-serialize

?? 什么是 OpenAPI？

OpenAPI（原 Swagger）是一種開放標(biāo)準(zhǔn)，用于描述和文檔化 RESTful API。通過標(biāo)準(zhǔn)化的格式（如 JSON 或 YAML），開發(fā)者可以清晰地定義接口路徑、請求參數(shù)、響應(yīng)結(jié)構(gòu)以及示例值等信息，從而幫助前后端協(xié)作、測試自動(dòng)化以及生成客戶端 SDK。

?? php-serialize 簡介

php-serialize 是一個(gè)功能強(qiáng)大的基于屬性（attribute）的 PHP 序列化庫（需要 PHP ≥ 8.1）。
它允許你將對象映射為數(shù)組或 JSON，并且可以基于相同的屬性 自動(dòng)生成 OpenAPI 文檔。

?? 統(tǒng)一解決方案，支持 API 數(shù)據(jù)序列化和文檔生成。

?? 核心特性

• ? 支持 OpenAPI 3.0 規(guī)范
• ? 自動(dòng)從 Serialize 對象生成文檔結(jié)構(gòu)
• ? 支持注解（Annotation）定義接口元數(shù)據(jù)
• ? 支持字段說明、示例值、分組控制等高級(jí)功能
• ? 可與 Laravel、Symfony 等主流框架無縫集成

??? 快速開始

使用 Composer 安裝：

composer  require  astral/serialize

創(chuàng)建Request

use Astral\Serialize\Serialize;

class UserAddRequest extends Serialize {
    public string $name;
    public int $id;
}

class UserDetailRequest extends Serialize {
    public int $id;
}

創(chuàng)建Repose

use Astral\Serialize\Serialize;

class UserDto extends Serialize {
    public string $name,
    public int $id;
}

創(chuàng)建Controller

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();
    }
}

啟動(dòng)服務(wù)

Docker啟動(dòng)

進(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

訪問 http://127.0.0.1:8089 查看Json文檔
訪問 http://127.0.0.1:8089/docs 查看UI文檔

?? 總結(jié)

php-serialize 提供了一種優(yōu)雅的方式來實(shí)現(xiàn) API 數(shù)據(jù)序列化與文檔自動(dòng)生成，具有以下優(yōu)勢：

• 聲明式注解：通過屬性注解完成接口定義。
• 類型安全：自動(dòng)處理復(fù)雜類型的輸入輸出轉(zhuǎn)換。
• 文檔同步更新：代碼即文檔，減少維護(hù)成本。
• 輕量靈活：不依賴特定框架，兼容主流項(xiàng)目架構(gòu)。

如果你正在尋找一個(gè)輕量級(jí)但功能強(qiáng)大的 API 文檔生成方案，不妨試試 php-serialize！