如何在OpenAPI的securitySchemes中定义UUID格式的API Key Schema？

首先明确：OpenAPI 3.x规范里，apiKey类型的安全方案不支持直接使用schema或format字段，这两个字段不属于该类型的合法属性，所以你的两次尝试才会触发验证报错。

不过可以通过以下两种方式实现类似需求：

方法1：在API操作中单独定义参数Schema #

securityScheme仅用于声明认证方式，具体的API Key格式要求可以在对应的接口路径/操作里，对authToken这个header参数单独定义Schema，明确指定其为UUID格式。这种方式符合规范，且能被验证工具识别：

openapi: 3.0.3
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: authToken
paths:
  /example-endpoint:
    get:
      security:
        - ApiKeyAuth: []
      parameters:
        - name: authToken
          in: header
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 请求成功

方法2：使用OpenAPI扩展字段标注 #

如果只是需要在文档里说明API Key是UUID格式，不需要强制验证，可以用OpenAPI的扩展字段（以x-开头）来标注，虽然不会被验证工具强制检查，但能清晰传达格式要求：

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: authToken
      x-format: uuid

补充说明 #

OpenAPI 3.x对apiKey类型安全方案的合法属性做了严格限制，仅允许type、description、name、in这几个字段。schema和format属于参数定义或http类型安全方案（比如Bearer Token）的属性，因此不能直接用在apiKey类型的securityScheme中。

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