使用 php-serialize 自动生成 OpenAPI 文档：高效构建 API 接口文档的利器

在现代 Web 开发中，清晰、规范的接口文档对于团队协作和系统集成至关重要。php-serialize 是一个基于 PHP 8.1+ 属性（Attribute）的序列化库，它不仅支持对象与数组之间的智能转换，还提供了一套强大的 OpenAPI 文档自动生成能力。

本文将带你快速了解如何使用 php-serialize 的 OpenAPI 功能来自动生成接口文档，并展示其在实际开发中的优势。

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

📦 什么是 OpenAPI？

OpenAPI（原 Swagger）是一种开放标准，用于描述和文档化 RESTful API。通过标准化的格式（如 JSON 或 YAML），开发者可以清晰地定义接口路径、请求参数、响应结构以及示例值等信息，从而帮助前后端协作、测试自动化以及生成客户端 SDK。

🚀 php-serialize 简介

php-serialize 是一个功能强大的基于属性（attribute）的 PHP 序列化库（需要 PHP ≥ 8.1）。
它允许你将对象映射为数组或 JSON，并且可以基于相同的属性 自动生成 OpenAPI 文档。

🚀 统一解决方案，支持 API 数据序列化和文档生成。

🧩 核心特性

• ✅ 支持 OpenAPI 3.0 规范
• ✅ 自动从 Serialize 对象生成文档结构
• ✅ 支持注解（Annotation）定义接口元数据
• ✅ 支持字段说明、示例值、分组控制等高级功能
• ✅ 可与 Laravel、Symfony 等主流框架无缝集成

🛠️ 快速开始

使用 Composer 安装：

composer  require  astral/serialize

创建Request

use Astral\Serialize\Serialize;

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

class UserDetailRequest extends Serialize {
    public int $id;
}

创建Repose

use Astral\Serialize\Serialize;

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

创建Controller

use Astral\Serialize\Serialize;
use Astral\Serialize\OpenApi\Enum\MethodEnum;

#[\Astral\Serialize\OpenApi\Annotations\Tag('用户模块管理')]
class UserController {

    #[\Astral\Serialize\OpenApi\Annotations\Summary('创建用户')]
    #[\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();
    }
}

启动服务

Docker启动

进入项目根目录

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文档

🎁 总结

php-serialize 提供了一种优雅的方式来实现 API 数据序列化与文档自动生成，具有以下优势：

• 声明式注解：通过属性注解完成接口定义。
• 类型安全：自动处理复杂类型的输入输出转换。
• 文档同步更新：代码即文档，减少维护成本。
• 轻量灵活：不依赖特定框架，兼容主流项目架构。

如果你正在寻找一个轻量级但功能强大的 API 文档生成方案，不妨试试 php-serialize！