Swagger-PHP 中属性意外标记为 Deprecated 的问题解析

问题现象

在使用 Swagger-PHP 生成 API 文档时，开发者发现某个 Schema 下的所有属性都被错误地标记为"Deprecated"状态。经过排查，发现问题源于类注释中的 @deprecated 标记会影响到整个 Schema 的属性定义。

问题根源

该问题的核心在于 PHP 文档注释中 @deprecated 标记的作用范围理解。在 PHP 文档标准中，@deprecated 标记会应用于其关联的结构元素。当在类注释中使用 @property 声明并标记某个属性为 @deprecated 时，这个标记实际上会影响整个类的定义，进而导致 Swagger-PHP 在生成文档时将类中的所有属性都视为已弃用。

解决方案

目前有两种可行的解决方案：

1. 显式设置 deprecated 属性：在每个 OA\Property 定义中明确设置 deprecated: false 参数，强制覆盖默认行为。

2. 调整注释位置：将 @deprecated 标记从类注释的 @property 声明中移除，改为在类方法或属性上直接使用 @deprecated 标记，这样可以更精确地控制弃用范围。

最佳实践建议

为避免此类问题，建议开发者在处理 API 文档时：

• 谨慎使用类级别的 @property 注释，特别是当需要标记弃用状态时
• 优先使用属性或方法级别的 @deprecated 标记
• 在 Swagger-PHP 的 OA\Property 定义中显式设置 deprecated 状态
• 保持文档注释的精确性和针对性，避免影响范围扩散

技术背景

Swagger-PHP 在解析 PHP 文档注释时会综合考虑各种标记的影响范围。@deprecated 作为 PHP 文档标准的一部分，其行为遵循 PHP 文档规范。理解这些标记的实际作用范围对于生成准确的 API 文档至关重要。