PHP 中使用 Swagger-PHP 实现泛型响应模型的正确实践

PHP 中使用 Swagger-PHP 实现泛型响应模型的正确实践

本文介绍如何在 PHP 项目中借助 zircote/swagger-php 精确描述泛型 HTTP 响应结构（如 HttpResponse），避免 anyOf 导致的类型歧义，推荐采用 allOf 组合基类与具体数据模型的方式生成清晰、准确的 OpenAPI 文档。

在构建 RESTful API 时，设计一个统一的响应格式——比如包含 `data`、`messages`、`statusCode` 等字段的 `HttpResponse`——几乎是标准操作。但问题来了：PHP 本身并不支持原生泛型，而 Swagger-PHP 默认也无法理解这种模式。如果直接在模型类里用 `@OA\Property(anyOf={...})` 去描述 `data` 字段，生成的 OpenAPI 文档会是什么样子？它会把所有可能的类型一股脑儿列出来，让每个接口的响应看起来都像是个“开盲盒”的结构。这显然不符合实际契约，毕竟每个接口返回的 `T` 是确定的，同时也让前端生成 SDK 和阅读文档的体验大打折扣。

✅ 推荐方案：分离基类 + 接口级响应定义

那么，有没有更优雅的解法？核心思路其实很清晰：不要把泛型的逻辑硬塞进一个模型类里，而是把通用结构和具体数据拆开。在每个接口的 `@OA\Response` 注解中，再利用 `allOf` 将它们明确地组合起来。 这样一来，代码复用性得以保持，OpenAPI 规范也能精准地映射真实的 API 响应，两全其美。

具体怎么做？我们分三步走。

首先，定义一个不包含 `data` 字段的通用响应基类 `BaseResponse`。它只负责承载那些每个接口都有的公共字段，比如消息列表和状态码。

/**
 * @OA\Schema(schema="BaseResponse", description="基础响应结构")
 */
class BaseResponse
{
    /**
     * @OA\Property(
     *     type="array",
     *     description="业务消息列表",
     *     @OA\Items(ref="#/components/schemas/Message")
     * )
     */
    public $messages;

    /**
     * @OA\Property(
     *     ref="#/components/schemas/HttpResponseType",
     *     description="HTTP 状态码枚举"
     * )
     */
    public $statusCode;
}

接着，定义具体的业务数据模型。例如，一个假期申请专用的输入数据结构。

/**
 * @OA\Schema(schema="HolidayRequestSpecificInput", description="假期申请专用数据结构")
 */
class HolidayRequestSpecificInput
{
    /**
     * @OA\Property(type="string", example="BEIJING")
     */
    public $location;

    /**
     * @OA\Property(type="string", format="date", example="2025-06-15")
     */
    public $startDate;
}

最后，也是最关键的一步，在控制器的方法注解里，为每个具体的 API 端点声明完整的响应结构。这里就是 `allOf` 大显身手的地方。

立即学习“PHP免费学习笔记（深入）”；

/**
 * @OA\Get(
 *     path="/api/holidays",
 *     summary="获取可用假期日期",
 *     @OA\Response(
 *         response="200",
 *         description="请求成功",
 *         @OA\JsonContent(
 *             allOf={
 *                 @OA\Schema(ref="#/components/schemas/BaseResponse"),
 *                 @OA\Schema(
 *                     @OA\Property(
 *                         property="data",
 *                         ref="#/components/schemas/A vailableHolidayDatesApiModel"
 *                     )
 *                 )
 *             }
 *         )
 *     ),
 *     @OA\Response(
 *         response="400",
 *         description="参数错误",
 *         @OA\JsonContent(ref="#/components/schemas/BaseResponse")
 *     )
 * )
 */
public function listHolidays() { /* ... */ }

⚠️ 关键注意事项

• ❌ 切忌在 `HttpResponse` 类内部使用 `anyOf` 或 `oneOf` 来定义 `data` 属性。这两个关键词表达的是“多选一”的语义，而我们的每个接口实际只返回一种确定的类型。
• ✅ 必须为每一个 `@OA\Response` 显式指定 `@OA\JsonContent(allOf={...})`。指望 `BaseResponse` 自动注入 `data` 字段？Swagger-PHP 可没这么智能。
• ? 如果想复用某个 `data` 的类型定义，一个好习惯是配合 `@OA\Schema(schema="...")` 给模型显式命名，这样可以确保 `$ref` 引用能被正确解析。
• ? `allOf` 是 OpenAPI 3.0 及以上版本中实现“继承与扩展”的标准方式，Swagger UI 以及主流的客户端代码生成器（比如 `openapi-generator`）都能很好地识别和支持它。

采用这套模式后，生成的 OpenAPI 文档里，每个 200 响应都会清晰、准确地呈现为：

{
  "messages": [...],
  "statusCode": "...",
  "data": { "location": "...", "startDate": "..." }
}

而不是那种令人困惑的 `"data": { oneOf: [ {...}, {...} ] }` 模糊结构。这不仅仅提升了 API 契约的可信度和可读性，更为后续的自动化测试、Mock 服务搭建以及 TypeScript 客户端代码生成，打下了坚实可靠的基础。说到底，清晰的约定胜过隐晦的猜测。