如何在Springdoc OpenAPI Swagger UI中执行HAWK签名的REST方法？

结论：原生Swagger UI不直接支持HAWK签名，因为OpenAPI 3.x规范里并没有定义HAWK这种安全方案类型，你之前用的@SecurityScheme(type = SecuritySchemeType.APIKEY)是针对API密钥认证的，和HAWK的动态签名逻辑完全不匹配。不过可以通过自定义Swagger UI的请求拦截逻辑来实现，具体步骤如下：

解决方案：自定义Swagger UI请求拦截器生成HAWK签名 #

我们可以通过springdoc-openapi的配置能力，注入自定义JavaScript脚本，拦截Swagger UI发送的所有请求，手动生成HAWK签名并添加到请求头中。

1. 准备前端HAWK库 #

下载hawk.js的最新版本，将其放到项目的src/main/resources/static/js目录下。

2. 配置SpringDoc加载自定义脚本 #

创建Swagger配置类，指定加载hawk.js和自定义的签名脚本：

import org.springdoc.core.SwaggerUiConfigParameters;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public SwaggerUiConfigParameters swaggerUiConfigParameters() {
        SwaggerUiConfigParameters config = new SwaggerUiConfigParameters();
        // 加载本地的hawk.js和自定义签名脚本
        config.addAdditionalScriptUrl("/js/hawk.min.js");
        config.addAdditionalScriptUrl("/js/hawk-sign.js");
        return config;
    }
}

3. 编写自定义签名拦截脚本 #

在src/main/resources/static/js下创建hawk-sign.js，实现请求拦截和签名生成：

window.addEventListener('load', function() {
    const ui = window.ui;
    if (!ui) return;

    // 存储HAWK凭证（用户输入的ID和密钥）
    let hawkCredentials = { id: '', key: '', algorithm: 'sha256' };

    // 在Swagger UI顶部添加凭证输入区域
    const hawkAuthPanel = document.createElement('div');
    hawkAuthPanel.style.padding = '10px 20px';
    hawkAuthPanel.innerHTML = `
        <span style="margin-right:10px;">HAWK ID:</span>
        <input type="text" id="hawkId" style="margin-right:10px;" placeholder="HAWK Client ID">
        <span style="margin-right:10px;">HAWK Key:</span>
        <input type="text" id="hawkKey" style="margin-right:10px;" placeholder="HAWK Client Key">
        <button onclick="saveHawkCreds()">Set Credentials</button>
    `;
    document.querySelector('.swagger-ui .topbar-wrapper').appendChild(hawkAuthPanel);

    // 保存用户输入的凭证
    window.saveHawkCreds = function() {
        hawkCredentials.id = document.getElementById('hawkId').value.trim();
        hawkCredentials.key = document.getElementById('hawkKey').value.trim();
    };

    // 拦截Swagger UI的请求，添加HAWK签名头
    ui.getHttpClient().interceptors.request.use(function(request) {
        if (!hawkCredentials.id || !hawkCredentials.key) {
            alert('请先输入HAWK ID和密钥');
            return Promise.reject('未设置HAWK凭证');
        }

        // 构建HAWK签名所需的请求参数
        const hawkOpts = {
            url: request.url,
            method: request.method,
            payload: request.body ? JSON.stringify(request.body) : '',
            contentType: request.headers['Content-Type'] || 'application/json'
        };

        // 生成HAWK Authorization头
        const hawkHeader = hawk.client.header(hawkOpts.url, hawkOpts.method, hawkOpts, hawkCredentials);
        request.headers['Authorization'] = hawkHeader.field;

        return request;
    });
});

4. 验证效果 #

启动项目后，打开Swagger UI页面（默认路径/swagger-ui.html），在顶部输入你的HAWK客户端ID和密钥，点击"Set Credentials"，之后发送的所有请求都会自动带上HAWK签名的Authorization头，后端的hawk-core就能正常验证签名了。

补充说明 #

• OpenAPI规范本身没有HAWK安全方案的定义，所以无法通过@SecurityScheme注解直接配置，必须通过自定义脚本实现。
• 确保后端已经正确集成hawk-core的验证逻辑，比如拦截所有请求并验证HAWK签名，否则即使请求带了签名也会被拒绝。

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