使用PHP Attributes添加OpenAPI 3.0自定义x-*扩展属性的问题

这里提供两种可行方案来处理PHP变量命名限制与OpenAPI自定义属性的冲突：

方案1：使用swagger-php官方的Extension属性 #

swagger-php专门提供了Extension属性来适配OpenAPI的自定义扩展（x-*格式属性），完全避开PHP变量名不能含连字符的限制：

use OpenApi\Attributes as OA;

#[OA\Get(
    path: "/api/example",
    summary: "示例接口",
    extensions: [
        new OA\Extension(
            property: "x-custom",
            value: "自定义属性内容"
        )
    ]
)]
public function exampleAction() {
    // 接口业务逻辑
}

生成的OpenAPI文档会自动包含"x-custom": "自定义属性内容"字段，完全符合规范要求。

方案2：通过数组或带引号的参数传递 #

部分版本的swagger-php支持直接通过数组或带引号的参数名传递自定义属性，利用PHP数组键名允许含连字符的特性：

数组形式 #

use OpenApi\Attributes as OA;

#[OA\Get(
    path: "/api/example",
    summary: "示例接口",
    x: [
        "custom" => "自定义属性内容"
    ]
)]
public function exampleAction() {
    // 接口业务逻辑
}

带引号的参数名形式 #

use OpenApi\Attributes as OA;

#[OA\Get(
    path: "/api/example",
    summary: "示例接口",
    'x-custom' => "自定义属性内容"
)]
public function exampleAction() {
    // 接口业务逻辑
}

注意：这种方式存在版本兼容性问题，建议先在当前使用的swagger-php版本中测试验证。

优先级建议 #

优先选择方案1，因为Extension是swagger-php官方推荐的自定义扩展处理方式，兼容性最强，也更贴合OpenAPI规范的设计逻辑。

内容的提问来源于stack exchange，提问作者darvinde