OpenAPI使用枚举作为路径参数时值自动添加引号如何解决

问题根因 #

从下拉选择框选中枚举值后，参数被URL编码的双引号包裹为%22summary%22格式，核心是Swagger/OpenAPI UI的参数序列化逻辑错误：工具错误将路径参数按照JSON字符串规则序列化，给纯文本的枚举值额外包裹了双引号。
问题复现截图：

给出的接口定义本身无语法错误，问题诱因通常是参数未显式声明序列化风格、或使用的Swagger UI版本存在已知bug。

修复方案 #

按优先级从高到低尝试：

• 显式声明路径参数的序列化规则，覆盖工具的错误默认逻辑。OpenAPI 3.0规范中路径参数默认序列化风格为simple（直接拼接纯文本值，不做JSON转换），但部分版本的文档工具未正确读取默认规则，手动给profile参数补充style和explode字段即可，修改后的参数定义如下：

profile:
  name: profile
  description: profile type either field or summary
  in: path
  required: true
  style: simple
  explode: false
  schema:
    type: string
    enum: [ field, summary ]

对应接口路径定义无需调整，保持原有写法即可：

/v1/metrics/{profile}:
  parameters:
    - $ref: "#/components/parameters/profile"
  get:
    summary: Get list of field or summary profile metrics
    description: Retrieves list of metrics for field or summary profile
    tags:
      - profile-metrics
    responses:
      '200':
        description: OK
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProfileMetrics"
      '400':
        $ref: "#/components/responses/BadRequest"
      '404':
        $ref: "#/components/responses/NotFound"
      default:
        $ref: "#/components/responses/UnexpectedError"

• 私有化部署Swagger UI的场景下，可通过请求拦截器统一修正路径参数格式，无需修改OpenAPI定义。在Swagger UI初始化配置中添加拦截逻辑，自动替换路径中被URL编码的多余引号：

const ui = SwaggerUIBundle({
  // 保留原有url、dom_id、presets等基础配置
  requestInterceptor: (request) => {
    request.url = request.url.replace(/%22([a-zA-Z0-9_-]+)%22/g, '$1')
    return request
  }
})

• 排查Swagger UI版本：3.18.x~3.22.x区间的版本存在路径枚举值序列化的已知bug，升级到3.23.0及以上稳定版本，无需额外修改配置即可自动修复问题。

注意：无需为适配该问题调整后端接口的参数接收逻辑，问题仅存在于API文档工具的前端参数序列化层，后端保持原有纯字符串枚举值（field/summary）的接收逻辑即可。

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