如何在Swagger中实现Google reCAPTCHA？Lumen API集成咨询

当然可以在Swagger中实现Google隐形reCAPTCHA验证！针对你的Lumen REST API场景，我整理了一套落地的实现步骤，一步步来就行：

1. 在Swagger注解中声明reCAPTCHA参数 #

首先要在你的API接口的Swagger注解里，明确标记需要接收reCAPTCHA验证token。通常我们会把token放在请求头里，这样更通用：

/**
 * @OA\Post(
 *     path="/api/your-protected-endpoint",
 *     summary="需要reCAPTCHA验证的接口",
 *     @OA\Parameter(
 *         name="X-Recaptcha-Token",
 *         in="header",
 *         required=true,
 *         @OA\Schema(type="string"),
 *         description="Google隐形reCAPTCHA生成的验证token"
 *     ),
 *     // 其他请求参数、响应定义...
 * )
 */

这样Swagger文档里就会显示这个必填参数，提示调用者需要携带它。

2. 后端添加reCAPTCHA验证中间件 #

既然你已经在Web面板用了reCAPTCHA，应该有现成的验证逻辑，我们把它封装成中间件，方便给需要保护的API路由统一加验证：

第一步：创建中间件文件 #

在app/Http/Middleware下新建RecaptchaMiddleware.php：

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;

class RecaptchaMiddleware
{
    public function handle(Request $request, Closure $next)
    {
        // 从请求头获取token
        $token = $request->header('X-Recaptcha-Token');
        
        if (!$token) {
            return response()->json(['error' => 'reCAPTCHA token缺失'], 400);
        }

        // 调用Google的验证接口校验token
        $response = Http::post('https://www.google.com/recaptcha/api/siteverify', [
            'secret' => env('RECAPTCHA_SECRET_KEY'), // 你的secret key，存在.env里
            'response' => $token,
            'remoteip' => $request->ip()
        ]);

        $verifyResult = $response->json();
        
        if (!$verifyResult['success']) {
            return response()->json([
                'error' => 'reCAPTCHA验证失败',
                'details' => $verifyResult['error-codes'] ?? []
            ], 403);
        }

        return $next($request);
    }
}

第二步：注册中间件 #

打开bootstrap/app.php，在路由中间件部分注册这个中间件：

$app->routeMiddleware([
    'recaptcha' => App\Http\Middleware\RecaptchaMiddleware::class,
]);

第三步：给需要保护的路由加中间件 #

在你的路由文件里，给目标API加上recaptcha中间件：

$router->post('/api/your-protected-endpoint', [
    'middleware' => 'recaptcha', 
    'uses' => 'YourController@yourMethod'
]);

3. 改造Swagger UI自动获取并携带token #

隐形reCAPTCHA不需要用户手动点击验证按钮，会自动生成token，我们需要让Swagger UI加载reCAPTCHA脚本，自动获取token并加到请求里：

第一步：配置自定义JS脚本 #

如果你用的是darkaonline/l5-swagger包，打开config/l5-swagger.php，找到ui配置项，添加自定义JS的路径：

'ui' => [
    'custom_js' => resource_path('js/swagger-custom.js'),
    // 其他UI配置...
],

第二步：编写自定义JS脚本 #

在resources/js下新建swagger-custom.js，内容如下（记得替换成你的site key）：

// 加载Google reCAPTCHA脚本
(function() {
    const siteKey = '你的Google reCAPTCHA Site Key';
    const script = document.createElement('script');
    script.src = `https://www.google.com/recaptcha/api.js?render=${siteKey}`;
    script.async = true;
    script.onload = function() {
        // 脚本加载完成后，获取验证token
        grecaptcha.ready(function() {
            // 这里的action可以根据你的业务调整，比如设为"api_access"
            grecaptcha.execute(siteKey, {action: 'api_request'}).then(function(token) {
                window.recaptchaToken = token;
                // 自动把token填充到Swagger的API密钥区域
                const ui = window.ui;
                ui.preauthorizeApiKey('X-Recaptcha-Token', token);
            });
        });
    };
    document.head.appendChild(script);
})();

// 拦截Swagger的请求，确保每次请求都带上最新的token
window.addEventListener('load', function() {
    const ui = window.ui;
    ui.getConfigs().requestInterceptor = function(request) {
        if (window.recaptchaToken) {
            request.headers['X-Recaptcha-Token'] = window.recaptchaToken;
        }
        return request;
    };

    // 定时刷新token（因为token有效期大概2分钟）
    setInterval(function() {
        const siteKey = '你的Google reCAPTCHA Site Key';
        grecaptcha.ready(function() {
            grecaptcha.execute(siteKey, {action: 'api_request'}).then(function(token) {
                window.recaptchaToken = token;
                ui.preauthorizeApiKey('X-Recaptcha-Token', token);
            });
        });
    }, 60 * 1000); // 每分钟刷新一次
});

4. 测试验证 #

启动你的Lumen服务，打开Swagger UI页面：

1. 页面加载完成后，会自动加载reCAPTCHA脚本并获取token
2. 访问需要保护的API接口，发送请求时，Swagger会自动带上X-Recaptcha-Token请求头
3. 如果token无效或者缺失，后端会返回对应的错误；验证通过则正常处理API请求

一些注意事项 #

• 确保在Google reCAPTCHA控制台里，把Swagger UI的域名（比如localhost:8000）加入允许的域名列表，否则验证会失败
• 隐形reCAPTCHA的token有效期约为2分钟，所以我们在脚本里加了定时刷新，避免token过期导致请求失败
• 如果你的API是通过请求体接收token，只需要调整Swagger注解的参数位置，以及前端脚本把token加到请求body里即可

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