如何为OpenApi/NelmioApiDoc的所有路由添加全局参数？

针对你遇到的「无法通过基类/接口注解全局添加请求头参数」的问题，这里提供两种基于swagger-php的全局配置方案：

方案一：根文档全局参数定义 #

创建一个单独的全局配置文件（比如swagger-global.php），在其中通过@OA\OpenApi注解定义全局参数，确保该文件会被swagger-php的扫描命令覆盖到：

<?php
/**
 * @OA\OpenApi(
 *     parameters={
 *         @OA\Parameter(
 *             name="x-locale",
 *             in="header",
 *             description="Locale for siteaccess matching",
 *             required=false, // 根据业务需求设置是否必填
 *             @OA\Schema(
 *                 type="string",
 *                 example="en_US" // 可选，添加示例值便于文档阅读
 *             )
 *         )
 *     }
 * )
 */

当swagger-php生成API文档时，这个参数会自动附加到所有API路径的请求头中，无需在每个控制器或方法中重复添加注解。

方案二：全局组件参数+路径引用（更灵活） #

如果需要后续对参数进行复用或单独调整，可以采用「组件定义+全局引用」的方式：

1. 定义全局组件参数（放在swagger-php扫描范围内的任意文件中）：

<?php
/**
 * @OA\Components(
 *     parameters={
 *         @OA\Parameter(
 *             name="x-locale",
 *             in="header",
 *             description="Locale for siteaccess matching",
 *             required=false,
 *             @OA\Schema(type="string"),
 *             ref="#/components/parameters/x-locale"
 *         )
 *     }
 * )
 */

2. 在全局路径模板中引用该参数：

<?php
/**
 * @OA\PathItem(
 *     parameters={
 *         @OA\Parameter(ref="#/components/parameters/x-locale")
 *     }
 * )
 */

这种方式的优势是可以统一管理全局参数，后续修改只需调整组件定义即可，无需修改所有路由相关代码。

为什么基类/接口注解无效？ #

swagger-php默认不会将父类或接口上的@OA\Parameter注解自动继承到子类的方法路径中——注解的作用域仅限当前类/方法，不会自动向下传递到具体的API路由定义上，因此直接在基类添加注解无法生效。

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