如何在OpenAPI 3中传递含空格的查询参数？

问题分析 #

直接传递未编码的空格（如http://localhost:8080/test?username=User Name）不符合URL规范，多数服务器会直接判定为无效请求返回"bad request"，这和OpenAPI规范本身的配置没有直接关联，而是URL编码的基础规则问题。

解决步骤 #

1. 对空格进行URL编码 #

按照RFC 3986标准，查询参数中的空格必须编码为%20（通用编码）或+（仅在查询字符串中适用）。正确的请求URL应该是：

• http://localhost:8080/test?username=User%20Name
• 或者 http://localhost:8080/test?username=User+Name

大多数HTTP客户端（如Postman、Axios、浏览器）会自动帮你完成编码，手动构造URL时需要注意自行编码。

2. 确认OpenAPI规范配置 #

你的现有规范中设置的allowReserved: true是用来允许传递RFC定义的保留字符（如:/?#[]@!$&'()*+,;=），空格不属于保留字符范畴，所以这个配置对空格的处理没有影响。只需保证schema.type为string即可，无需额外配置：

/test:
  get:
    description: Pass name
    parameters:
      - name: username
        in: query
        required: true
        schema:
          type: string

3. 服务器端适配（若仍有问题） #

如果已经正确编码但服务器仍返回错误，需要检查服务器框架的配置：

• 确保服务器支持解析编码后的空格（多数主流框架如Spring Boot、Express默认支持）。
• 若必须支持未编码的空格（不推荐，违反URL规范），需要修改服务器的请求解析规则，比如在Spring Boot中调整server.tomcat.relaxed-query-chars参数允许空格。

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