使用openapi-generator-cli生成代码后Postman测试报400错误求助

问题还原 #

用openapi-generator-cli基于官方petstore.yaml生成代码，Postman测试时返回400错误，提示：

{
"message": "request should have required property 'headers'",
"errors": [
{
"path": ".headers",
"message": "should have required property 'headers'",
"errorCode": "required.openapi.validation"
}
]
}
自行编写yaml文件后问题仍存在，未修改过生成的代码。

排查与解决步骤 #

• 检查OpenAPI定义的请求体结构
  问题核心几乎都是yaml里把headers错误定义成了请求体的必填字段。比如如果你的接口定义里有类似这段代码：

  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
            - headers
          properties:
            headers:
              type: object
  

  这种写法会让生成的代码强制要求请求体里必须包含headers字段，但正常场景下我们是把请求头放在HTTP Headers里，而非请求体。

• 区分HTTP请求头和请求体字段
  要定义HTTP请求头，应该用OpenAPI的parameters节点，指定in: header，而非放在requestBody的schema中。正确示例：

  parameters:
    - name: X-Request-ID
      in: header
      required: true
      schema:
        type: string
  

  这样生成的代码会把该字段识别为HTTP请求头，Postman直接在Headers标签下添加即可，无需在请求体中传入。

• 验证生成代码的逻辑
  打开生成的接口参数模型类（比如Java的DTO、Python的Pydantic模型），查看是否有headers字段被标记为必填。如果有，说明你的yaml定义确实存在问题，需要调整。

• 修正后重新生成并测试

  1. 修改yaml文件，移除请求体schema中对headers的必填要求，或者将HTTP请求头的定义移到parameters节点。
  2. 重新生成代码：openapi-generator-cli generate -i your-modified.yaml -g [你的目标语言，如spring/flask] -o ./output
  3. Postman测试时，将需要的头信息放在Headers标签下，请求体中不再包含headers字段。

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