OpenAPI生成的Python客户端处理204 No Content响应异常问题

使用openapitools/openapi-generator-cli工具从OpenAPI规范生成Python客户端时，调用可能返回204 No Content状态码的GET接口触发错误。

OpenAPI规范中的接口定义 #

'/api/v1/Sensor/now/{instanceUri}':
  get:
    tags:
      - Sensor
    parameters:
      - name: instanceUri
        in: path
        required: true
        schema:
          type: string
      - name: x-api-version
        in: header
        schema:
          type: string
    responses:
      '200':
        description: Success
        content:
          text/plain:
            schema:
              $ref: '#/components/schemas/Gkkg.Bff.Api.Contracts.TagValueResponses'
          application/json:
            schema:
              $ref: '#/components/schemas/Gkkg.Bff.Api.Contracts.TagValueResponses'
          text/json:
            schema:
              $ref: '#/components/schemas/Gkkg.Bff.Api.Contracts.TagValueResponses'
      '204':
        description: No Content
      '401':
        description: Unauthorized
      '403':
        description: Forbidden
    security:
      - Bearer:
          - sensor_read

生成客户端的问题 #

生成的客户端代码虽识别204响应码，但仍期望返回GkkgBffApiContractsTagValueResponses类型，导致204空响应时触发ApiTypeError：

ApiTypeError: Invalid type for variable 'received_data'. Required value type is GkkgBffApiContractsTagValueResponses and passed type was str at ['received_data']

直接用requests库发起请求可正常处理204响应。

生成的客户端函数信息 #

• 函数签名：GkkgBffApiContractsTagValueResponses api_v1_sensor_now_instance_uri_get(instance_uri)
• 返回类型：GkkgBffApiContractsTagValueResponses
• 示例调用代码：

import time
import gkkg_api_python_proxy
from gkkg_api_python_proxy.api import sensor_api
from gkkg_api_python_proxy.model.gkkg_bff_api_contracts_tag_value_responses import GkkgBffApiContractsTagValueResponses
from pprint import pprint

configuration = gkkg_api_python_proxy.Configuration(
    host = "http://localhost"
)

# Configure Bearer authorization (JWT): Bearer
configuration = gkkg_api_python_proxy.Configuration(
    access_token = 'YOUR_BEARER_TOKEN'
)

with gkkg_api_python_proxy.ApiClient(configuration) as api_client:
    api_instance = sensor_api.SensorApi(api_client)
    instance_uri = "instanceUri_example"  # str | 
    x_api_version = "x-api-version_example"  # str |  (optional)

    try:
        api_response = api_instance.api_v1_sensor_now_instance_uri_get(instance_uri)
        pprint(api_response)
    except gkkg_api_python_proxy.ApiException as e:
        print("Exception when calling SensorApi->api_v1_sensor_now_instance_uri_get: %s\n" % e)

    try:
        api_response = api_instance.api_v1_sensor_now_instance_uri_get(instance_uri, x_api_version=x_api_version)
        pprint(api_response)
    except gkkg_api_python_proxy.ApiException as e:
        print("Exception when calling SensorApi->api_v1_sensor_now_instance_uri_get: %s\n" % e)

疑问 #

1. 为何生成的Python客户端处理204 No Content响应时触发ApiTypeError，但Swagger UI可正常工作？
2. 如何调整OpenAPI规范，使Python客户端正确处理204响应？（不想修改生成的代码）

问题1原因 #

Swagger UI直接基于OpenAPI规范解析响应状态码，遇到204时会自动忽略响应体处理，不需要强制转换类型；而openapi-generator-cli生成Python客户端时，默认将接口返回类型绑定到200响应的模型，未针对204响应单独处理返回值——它仍尝试把空响应体解析为指定的GkkgBffApiContractsTagValueResponses模型，空内容无法匹配模型结构，因此抛出类型错误。

问题2解决方案 #

在OpenAPI规范的204响应中显式添加content: {}，明确告知生成工具该响应没有任何内容体，这样Python客户端会生成支持返回None或空值的逻辑，避免强制类型转换错误。

修改后的接口响应部分：

responses:
  '200':
    description: Success
    content:
      text/plain:
        schema:
          $ref: '#/components/schemas/Gkkg.Bff.Api.Contracts.TagValueResponses'
      application/json:
        schema:
          $ref: '#/components/schemas/Gkkg.Bff.Api.Contracts.TagValueResponses'
      text/json:
        schema:
          $ref: '#/components/schemas/Gkkg.Bff.Api.Contracts.TagValueResponses'
  '204':
    description: No Content
    content: {}  # 新增这一行
  '401':
    description: Unauthorized
  '403':
    description: Forbidden

添加content: {}后，openapi-generator-cli会识别204响应无内容，生成的客户端函数会处理空响应情况，不会再强制要求返回指定模型，调用204响应时就不会触发类型错误。

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