如何在Node.js的Swagger API中为POST接口创建查询参数？

对于你给出的POST请求示例（URL携带查询参数），可以按照以下方式在Swagger（OpenAPI）中定义对应的API：

核心逻辑 #

POST请求完全支持携带查询参数，在Swagger里只需将参数的in属性设为query即可。针对你示例里的两种参数类型（单个字符串、多值数组），配置方式如下：

完整Swagger YAML示例 #

openapi: 3.0.3
info:
  title: 职位搜索API
  version: 1.0.0
paths:
  /jobs/jobSearch:
    post:
      summary: 搜索职位
      parameters:
        - name: jobTitle
          in: query
          description: 职位名称关键词
          required: false # 根据实际业务需求设置是否必填
          schema:
            type: string
        - name: professionalField
          in: query
          description: 专业领域（支持多选）
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true # 启用后会生成 professionalField[]=xxx&professionalField[]=yyy 格式的参数
      responses:
        '200':
          description: 搜索结果返回
          content:
            application/json:
              schema:
                type: object
                description: 职位列表数据结构

关键配置说明 #

• 单个查询参数：比如jobTitle，直接定义type: string并指定in: query即可，按需设置是否必填。
• 数组类型查询参数：示例里的professionalField[]需要配置style: form和explode: true，这样Swagger会生成带[]后缀的多值参数格式，和你Postman中的请求URL格式完全匹配。如果不设置这两个属性，默认会生成professionalField=Finance,Bank,Insurances这种逗号分隔的格式，不符合需求。

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