Swagger/OpenAPI路由多参数配置问题：路径与请求体参数共存

我来帮你梳理下问题所在，以及不同OpenAPI版本下的正确配置方式：

OpenAPI 2.0（Swagger 2.0）的正确配置 #

你之前的配置失效，核心原因是请求体参数缺少schema定义。在OpenAPI 2.0规范里，in: body类型的参数必须通过schema明确指定请求体的结构，否则系统无法识别。正确配置示例如下：

swagger: "2.0"
info:
  title: 示例告警API
  version: 1.0.0
paths:
  /alerts/{alertId}:
    post:  # 根据实际请求方法调整，比如PUT/POST
      summary: 携带路径ID与请求体的告警处理接口
      parameters:
        - name: alertId
          in: path
          description: 告警ID
          required: true
          type: string
        - name: data
          in: body
          description: 告警相关数据对象
          required: true  # 若请求体必填则添加
          schema:
            type: object
            properties:
              # 这里定义data对象的具体字段，示例如下
              alertContent:
                type: string
              severity:
                type: integer
                enum: [1,2,3]
            required: [alertContent]  # 指定必填字段
      responses:
        200:
          description: 处理成功响应

OpenAPI 3.0+的正确配置 #

你切换到3.0版本后仍未解决，大概率是没注意到3.0已经废弃了in: body的参数写法，改用专门的requestBody字段来定义请求体内容，路径参数的配置则保持逻辑一致。正确配置示例：

openapi: 3.0.3
info:
  title: 示例告警API
  version: 1.0.0
paths:
  /alerts/{alertId}:
    post:
      summary: 携带路径ID与请求体的告警处理接口
      parameters:
        - name: alertId
          in: path
          description: 告警ID
          required: true
          schema:
            type: string
      requestBody:
        description: 告警相关数据对象
        required: true
        content:
          application/json:  # 指定请求体的媒体类型，如JSON/FormData等
            schema:
              type: object
              properties:
                alertContent:
                  type: string
                severity:
                  type: integer
                  enum: [1,2,3]
              required: [alertContent]
      responses:
        '200':
          description: 处理成功响应

核心注意事项 #

• OpenAPI 2.0中，in: body类型的参数只能有一个，且必须搭配schema定义结构；
• OpenAPI 3.0+中，请求体统一放在requestBody下，需通过content声明媒体类型（如application/json）；
• 路径参数的配置在两个版本中逻辑一致，确保in: path、required: true和类型定义正确即可。

内容的提问来源于stack exchange，提问作者Cátia Matos