使用 php-serialize 自动生成 OpenAPI 文档:高效构建 API 接口文档的利器
使用 php-serialize 自动生成 OpenAPI 文档:高效构建 API 接口文档的利器
在现代 Web 开发中,清晰、规范的接口文档对于团队协作和系统集成至关重要。php-serialize 是一个基于 PHP 8.1+ 属性(Attribute)的序列化库,它不仅支持对象与数组之间的智能转换,还提供了一套强大的 OpenAPI 文档自动生成能力。
本文将带你快速了解如何使用 php-serialize
的 OpenAPI 功能来自动生成接口文档,并展示其在实际开发中的优势。
php-serialize:github.com/astral-data/php-seriali...
📦 什么是 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
!
本作品采用《CC 协议》,转载必须注明作者和本文链接
推荐文章: