如何在OpenAPI 3.0.x版本中定义API的mTLS身份验证？

因为OAS 3.0.X原生不支持mTLS类型，只能通过自定义扩展+团队约定的方式实现文档层面的定义，以下是几种落地性强的实践思路：

1. 基于HTTP安全方案扩展标识 #

利用OpenAPI的自定义扩展字段（x-*），在securitySchemes中复用http类型，添加明确标识mTLS的扩展字段，同时补充清晰描述：

openapi: 3.0.3
info:
  title: 示例API
  version: 1.0.0
components:
  securitySchemes:
    MutualTLS:
      type: http
      scheme: mutual  # 用未定义的scheme做直观标识
      x-mtls: true    # 核心自定义扩展字段，明确标记为mTLS
      description: 访问此API需使用双向TLS认证，客户端必须提供服务端信任的有效证书
security:
  - MutualTLS: []

这种方式的核心是通过x-mtls让团队、工具链统一识别mTLS要求，scheme: mutual作为辅助标识，便于快速区分认证类型。

2. 接口层面精准标注 #

如果仅部分API需要mTLS，除了在security中引用上述安全方案，还可以在接口的description里强化说明：

paths:
  /sensitive/user-data:
    get:
      summary: 获取用户敏感数据
      description: 此接口**强制要求mTLS身份验证**，客户端证书需提前在服务端完成注册备案
      security:
        - MutualTLS: []
      responses:
        '200':
          description: 成功返回敏感数据

3. 关联网关配置的约定 #

OpenAPI定义更多是文档和协作规范，实际mTLS校验需要在API网关或服务端实现。可以通过扩展字段关联网关的具体策略：

components:
  securitySchemes:
    MutualTLS:
      type: http
      x-mtls: true
      x-gateway-mtls-policy: "strict-cert-validation"  # 关联网关的mTLS校验策略

实践注意事项 #

• 提前和团队、工具链（如API文档工具、网关配置工具）约定x-mtls等扩展字段的含义，确保各方能正确识别；
• OAS 3.0.x的原生工具可能不支持mTLS可视化展示，需要自定义插件或补充文档说明；
• 优先保证服务端/网关的mTLS配置正确，OpenAPI定义作为文档协作和合规校验的依据。

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