Symfony3.4项目中NelmioApiDocBundle结合OAuth2授权配置咨询

我之前在Symfony 3.4项目里正好做过这两个Bundle的集成，既然你已经用php bin/console fos:oauth-server:create-client --redirect-uri="___" --grant-type="authorization_code" --grant-type="password" --grant-type="refresh_token"搞定了FOSOAuthServerBundle的部署和客户端创建，那接下来只需要几步就能把OAuth2授权整合到API文档里，方便直接在文档页面测试带权限的接口：

1. 配置NelmioApiDocBundle支持OAuth2 #

首先在app/config/config.yml里添加Nelmio的OAuth2相关配置，告诉文档系统你的OAuth服务端点和授权类型：

nelmio_api_doc:
    documentation:
        security:
            - oauth2: []
        securityDefinitions:
            oauth2:
                type: oauth2
                # 这里对应你创建客户端时指定的授权类型，比如password/authorizationCode等
                flow: password
                tokenUrl: '/oauth/v2/token'
                # 如果用authorization_code流，需要添加下面这行
                # authorizationUrl: '/oauth/v2/auth'
                scopes:
                    read: '读取资源权限'
                    write: '写入资源权限'

注：如果主要使用authorization_code授权流，记得把flow改成authorizationCode，并补充authorizationUrl参数，值就是FOSOAuth的授权端点。

2. 给需要授权的API接口添加注解 #

在你的Controller方法上，通过@ApiDoc注解标记该接口需要OAuth2授权，还可以指定所需的权限范围（scope）：

use Nelmio\ApiDocBundle\Annotation\ApiDoc;

/**
 * 获取单个资源详情
 *
 * @ApiDoc(
 *  resource=true,
 *  authentication={"oauth2"},
 *  requirements={
 *      {"name"="id", "dataType"="integer", "requirement"="\d+", "description"="资源ID"}
 *  },
 *  scopes={"read"}
 * )
 */
public function showAction($id)
{
    // 你的接口业务逻辑
}

如果某个接口不需要授权，直接去掉authentication参数即可。

3. 在API文档页面测试授权 #

启动Symfony项目后，访问默认的API文档地址/api/doc，你会看到页面顶部多了一个Authorize按钮：

• 点击按钮后，根据你选择的授权流填入对应信息：比如password流需要填client_id、client_secret、用户的username和password；authorization_code流则需要跳转到授权页面登录授权
• 授权成功后，文档系统会自动把获取到的Bearer Token添加到后续所有接口请求的Authorization Header里，你就可以直接测试需要权限的接口了

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