如何为DRF Spectacular的Webhook添加HMAC等认证方式

要满足Redocly的安全校验要求，需完成两个核心操作：注册HMAC安全方案，再给Webhook操作绑定该方案。

步骤1：定义HMAC安全方案 #

先创建OpenApiSecurityScheme实例，描述HMAC认证规则（这里以请求头传递签名的常见实现为例）：

from drf_spectacular.openapi import OpenApiSecurityScheme

# 定义HMAC签名认证的安全方案
signature_auth_scheme = OpenApiSecurityScheme(
    name="signatureAuth",
    type="apiKey",
    in_="header",
    description="通过请求头传递HMAC签名完成Webhook身份验证",
)

步骤2：修改Webhook定义，绑定安全方案 #

在原Webhook的extend_schema中新增两个参数：

• components：将上述安全方案注册到OpenAPI组件库
• security：指定当前Webhook操作使用signatureAuth认证

修改后的完整代码：

from drf_spectacular.openapi import OpenApiWebhook, OpenApiResponse, OpenApiSecurityScheme
from drf_spectacular.utils import extend_schema, load_schema

# 定义HMAC签名认证的安全方案
signature_auth_scheme = OpenApiSecurityScheme(
    name="signatureAuth",
    type="apiKey",
    in_="header",
    description="通过请求头传递HMAC签名完成Webhook身份验证",
)

change_event_webhook = OpenApiWebhook(
    name="AddonWebhook",
    decorator=extend_schema(
        summary="A Webhook event",
        description="Pushes events to a notification URL. ",
        tags=["webhooks"],
        request={"application/json": load_schema("myschema.json")},
        responses={
            "2XX": OpenApiResponse("Event was received successfully"),
        },
        # 注册安全方案到OpenAPI组件
        components={"securitySchemes": {"signatureAuth": signature_auth_scheme}},
        # 指定当前操作使用该安全认证
        security=[{"signatureAuth": []}],
    ),
)

生成的OpenAPI Schema变化 #

修改后生成的Schema会新增两部分内容：

1. 全局components下的安全方案定义：

components:
  securitySchemes:
    signatureAuth:
      type: apiKey
      in: header
      name: signatureAuth
      description: 通过请求头传递HMAC签名完成Webhook身份验证

2. Webhook的post操作下的安全声明：

webhooks:
  AddonWebhook:
    post:
      # 原有字段...
      security:
      - signatureAuth: []
      # 原有字段...

这样就能满足Redocly的安全校验规则，解决"Every operation should have security defined on it or on the root level."的报错。

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