如何为L5-Swagger的所有Swagger请求注解统一添加公共参数？

当然有办法搞定这个重复配置的麻烦！Swagger/OpenAPI 本身就设计了可复用组件的特性，完美解决你不想重复写参数注解的问题，下面给你两种实用的实现方案：

方案1：使用OpenAPI全局组件定义与引用 #

这是最符合OpenAPI规范的做法，你可以把重复的参数定义在全局的OpenAPI组件里，之后在任何接口中直接引用即可：

首先，在你的Swagger全局配置文件（比如专门的Swagger配置类，或者项目的主入口注解里）定义这个可复用参数：

/**
 * @OA\OpenApi(
 *   components={
 *     @OA\Parameter(
 *       name="Content-Type",
 *       in="header",
 *       required=true,
 *       example="application/json",
 *       @OA\Schema(type="string")
 *     )
 *   }
 * )
 */

之后，在任意接口的注解中，只需要通过ref引用这个全局参数，不用再写完整的参数配置：

/**
 * @OA\Get(
 *   path="/api/user/list",
 *   summary="获取用户列表",
 *   @OA\Parameter(ref="#/components/parameters/Content-Type"),
 *   @OA\Response(response=200, description="请求成功")
 * )
 */
public function getUserList()
{
    // 接口逻辑
}

方案2：利用PHP Trait封装重复注解 #

如果你的项目用的是PHP框架（比如Laravel、Symfony），还可以用PHP的Trait特性来封装重复的Swagger参数注解，在需要的控制器中直接引入Trait即可自动带上这些参数：

先创建一个Trait文件，把重复的参数注解写进去：

trait SwaggerCommonHeaders
{
    /**
     * @OA\Parameter(
     *   name="Content-Type",
     *   in="header",
     *   required=true,
     *   example="application/json",
     *   @OA\Schema(type="string")
     * )
     */
    public function contentHeader() {}
}

然后在你的控制器类中引入这个Trait，对应的接口就会自动包含这个参数注解：

class UserController extends Controller
{
    use SwaggerCommonHeaders;

    /**
     * @OA\Get(
     *   path="/api/user/detail",
     *   summary="获取用户详情",
     *   @OA\Response(response=200, description="请求成功")
     * )
     */
    public function getUserDetail()
    {
        // 接口逻辑
    }
}

小提示 #

• 方案1更适合全局统一复用，尤其是团队协作时，能保证参数定义的一致性；
• 方案2是PHP特有的技巧，适合在项目内多个控制器快速复用一组通用参数。

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