OpenAPI Generator生成Go客户端：Header参数被转为Query参数的解决方法

使用OpenAPI Generator生成Go客户端时，规范里定义的X-Request-ID Header参数被错误识别为Query参数发送到服务器。

OpenAPI规范 #

info:
  title: API
  version: "1.2"
servers:
  - url: https://example.com
paths:
  /ping:
    get:
      summary: Checks if the server is alive
      parameters:
        - in: header
          name: X-Request-ID
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          description: Request has been successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  returned_url:
                    type: string

生成命令 #

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i /local/spec.yaml \
  -g go \
  -o /local/internal/infrastructure/sdk \
  -p enumClassPrefix=true \
  -p generateInterfaces=true \
  -p isGoSubmodule=true \
  -p packageName=sdk

生成代码中的错误逻辑 #

parameterAddToQuery(localVarQueryParams, "X-Request-ID", r.xRequestID, "")

请问这是Bug吗？该如何解决此问题？

这是OpenAPI Generator旧版本Go生成器的已知Bug，可通过以下方式解决：

1. 升级生成器版本
   使用最新稳定版的OpenAPI Generator镜像生成客户端，避免依赖默认的旧版本镜像：

   docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli:v7.6.0 generate \
     -i /local/spec.yaml \
     -g go \
     -o /local/internal/infrastructure/sdk \
     -p enumClassPrefix=true \
     -p generateInterfaces=true \
     -p isGoSubmodule=true \
     -p packageName=sdk
   

   新版本已修复Header参数被误解析为Query参数的问题。

2. 手动修正生成代码
   若暂时无法升级，直接修改生成的代码，将Query参数添加逻辑替换为Header设置：

   // 替换原有的parameterAddToQuery调用
   localVarHeaderParams["X-Request-ID"] = r.xRequestID
   

   确保代码中已定义localVarHeaderParams，若未定义则添加：

   localVarHeaderParams := make(map[string]string)
   

3. 校验规范格式
   确认OpenAPI规范的YAML语法无误，比如in: header字段的缩进、拼写正确，避免因格式问题导致生成器解析错误。

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