如何在OpenAPI 2.0中描述带API Key与请求体的POST接口？

嘿，我知道你卡在这个API Key的header配置上了！你遇到的Schema错误，根源是OpenAPI 2.0（Swagger 2.0）要求所有非-body类型的参数（比如header、query、path）必须明确指定schema字段，你的配置里刚好漏掉了这部分。

下面是修正后的完整配置，我还补充了一些必要的细节：

paths:
  /eau:
    post:
      tags:
        - Pets
      summary: Send a pet
      description: Submit a pet object to the API
      operationId: sendapet
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        # RequestBody参数：你的原始配置没问题
        - in: body
          name: pet
          description: The pet object to send
          required: true
          schema:
            $ref: '#/definitions/pet'
        # 修正后的API Key Header参数
        - in: header
          name: api_key
          description: Authentication API Key
          required: true  # 根据你的接口需求，设为false则表示可选
          schema:
            type: string  # API Key几乎都是字符串类型，这里必须指定
# 补充pet对象的定义示例（你可以根据实际结构调整）
definitions:
  pet:
    type: object
    properties:
      name:
        type: string
        description: Name of the pet
      species:
        type: string
        description: Species of the pet
      age:
        type: integer
        format: int32
        description: Age of the pet in years
    required:
      - name
      - species

关键修正点说明： #

• 添加schema字段：对于header类型的api_key参数，必须用schema指定数据类型（这里是string），这是OAS2.0的强制要求，没有它就会抛出Schema验证错误。
• 可选的required字段：我加了required: true，如果你的接口允许无API Key访问，可以改成false。
• 补充definitions示例：为了避免$ref引用出错，我添加了pet对象的基础结构，你可以根据实际的pet字段修改这部分。

额外优化建议： #

如果你的API Key有特定格式（比如JWT令牌），可以在schema里添加format字段来更清晰地描述：

schema:
  type: string
  format: jwt

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