使用 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 协议》,转载必须注明作者和本文链接
《L04 微信小程序从零到发布》
从小程序个人账户申请开始,带你一步步进行开发一个微信小程序,直到提交微信控制台上线发布。
《L02 从零构建论坛系统》
以构建论坛项目 LaraBBS 为线索,展开对 Laravel 框架的全面学习。应用程序架构思路贴近 Laravel 框架的设计哲学。
讨论数量: 0
(= ̄ω ̄=)··· 暂无内容!

讨论应以学习和精进为目的。请勿发布不友善或者负能量的内容,与人为善,比聪明更重要!