Swagger-PHP 中 Schema 对象的示例属性使用指南

概述

在 OpenAPI 规范 3.1.0 版本中，Schema 对象的示例属性发生了一些重要变化。本文将详细介绍如何在 Swagger-PHP 中正确处理 Schema 和 Property 对象的示例属性，帮助开发者避免常见的配置错误。

OpenAPI 3.1.0 中的变化

OpenAPI 3.1.0 规范对示例属性做了重要调整：

1. 单数形式的 example 属性已被标记为废弃
2. 复数形式的 examples 属性成为推荐用法
3. 对于多个示例的情况，必须使用 examples 属性

Swagger-PHP 中的实现

在 Swagger-PHP 中，开发者可以通过 OA\Schema 和 OA\Property 注解来定义 Schema 和属性级别的示例。最新版本已支持使用 examples 属性来定义多个示例。

正确用法示例

#[OA\Schema(
    schema: "import_props",
    title: "Import props",
    required: ["data", "entity_id", "mode"],
    examples: [
        new OA\Examples(
            example: "Example 1",
            summary: "创建模式示例",
            value: [
                "mode" => "create",
                "entity_id" => 1,
                "data" => "示例数据"
            ]
        ),
        new OA\Examples(
            example: "Example 2",
            summary: "更新模式示例",
            value: [
                "mode" => "update",
                "entity_id" => 1,
                "data" => "更新数据"
            ]
        )
    ]
)]

生成的 OpenAPI 文档

上述代码将生成符合规范的 OpenAPI 文档：

components:
  schemas:
    import_props:
      title: Import props
      required:
        - data
        - entity_id
        - mode
      examples:
        Example 1:
          summary: 创建模式示例
          value:
            mode: create
            entity_id: 1
            data: 示例数据
        Example 2:
          summary: 更新模式示例
          value:
            mode: update
            entity_id: 1
            data: 更新数据

常见问题与解决方案

1. 属性级别示例：对于 Property 级别的示例，同样应该使用 examples 而非 example 属性。

2. 数组形式的误解：虽然 PHP 代码中使用数组形式定义多个示例，但在生成的 OpenAPI 文档中，examples 是一个对象而非数组，这是符合规范的。

3. 向后兼容性：目前 Swagger-PHP 仍然支持 example 属性，但建议新项目直接使用 examples 以避免未来兼容性问题。

最佳实践建议

1. 对于新项目，统一使用 examples 属性
2. 为每个示例提供有意义的 summary 描述
3. 示例的 value 应该完整展示可能的用例
4. 定期验证生成的 OpenAPI 文档是否符合规范

通过遵循这些指南，开发者可以确保生成的 API 文档既符合最新规范，又能为 API 使用者提供清晰的使用示例。