如何在Symfony控制器中用swagger-php注解实现Bearer认证配置

你要的等效OpenAPI 3.0配置可以按以下方式编写，生成的JSON结构和你给出的示例完全一致：

1. 全局声明安全认证方案 #

安全方案属于OpenAPI全局配置，不需要在每个控制器重复编写。你可以在项目中任意位置添加全局OpenAPI基础注解，通常可以放在专门的配置类、或者基础控制器类上，示例代码：

<?php

namespace App\Controller;

use OpenApi\Annotations as OA;

/**
 * @OA\OpenApi(
 *     @OA\Info(title="你的Symfony API接口", version="1.0.0"),
 *     @OA\SecurityScheme(
 *         securityScheme="Bearer",
 *         type="http",
 *         description="Entrer le token JST",
 *         scheme="bearer",
 *         bearerFormat="JWT"
 *     )
 * )
 */
final class OpenApiConfig
{
    // 空类即可，不需要写业务逻辑
}

2. 全局开启Bearer认证 #

如果需要所有接口默认都要求携带Bearer Token，直接在全局@OA\OpenApi注解中添加security配置即可，修改后的全局注解：

/**
 * @OA\OpenApi(
 *     @OA\Info(title="你的Symfony API接口", version="1.0.0"),
 *     @OA\SecurityScheme(
 *         securityScheme="Bearer",
 *         type="http",
 *         description="Entrer le token JST",
 *         scheme="bearer",
 *         bearerFormat="JWT"
 *     ),
 *     security={{"Bearer": {}}}
 * )
 */
final class OpenApiConfig
{
}

执行文档生成命令后，输出的JSON配置会和你给出的示例完全匹配。

3. 控制器/单接口粒度的配置调整 #

• 如果不需要全局开启认证，仅对特定控制器或接口生效，把全局配置里的security项删除，在需要认证的控制器类或方法上添加@OA\Security注解即可：

<?php

namespace App\Controller;

use OpenApi\Annotations as OA;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

/**
 * @OA\Security("Bearer")
 */
class UserController extends AbstractController
{
    /**
     * @OA\Get(path="/api/user/info", summary="获取当前登录用户信息")
     */
    public function info()
    {
        // 业务逻辑
    }
}

• 如果全局开启了认证，个别公开接口（比如登录、公共资源接口）不需要校验Token，直接在对应方法上添加空security配置覆盖全局规则即可：

/**
 * @OA\Post(path="/api/login", summary="用户登录获取Token")
 * @OA\Security({})
 */
public function login()
{
    // 登录接口无需携带Token
}

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