关于OpenAPI 3.0.3/Swagger 2.0查询参数实现标准的咨询

你要找的查询参数规范其实包含在OpenAPI 3.0.3和Swagger 2.0的核心定义里，并非无据可依。只要你的写法符合这两个规范的要求，就完全能和REST风格兼容。

Swagger 2.0 中查询参数的定义方式 #

Swagger 2.0通过parameters数组定义查询参数，核心是指定in: query来标识参数位置：

swagger: '2.0'
info:
  title: 示例用户API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取分页用户列表
      parameters:
        - name: page
          in: query
          type: integer
          required: false
          description: 页码，默认1
        - name: size
          in: query
          type: integer
          required: false
          description: 每页条数，默认10
        - name: status
          in: query
          type: string
          enum: [active, inactive, suspended]
          required: false
          description: 用户状态过滤
      responses:
        200:
          description: 成功返回用户列表

OpenAPI 3.0.3 中查询参数的定义方式 #

OpenAPI 3.0.3在Swagger 2.0基础上做了扩展，用schema更灵活地定义参数类型，还支持控制数组/对象参数的序列化方式：

openapi: 3.0.3
info:
  title: 示例用户API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取分页用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          required: false
          description: 页码
        - name: size
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          required: false
          description: 每页条数
        - name: status
          in: query
          schema:
            type: string
            enum: [active, inactive, suspended]
          required: false
          description: 用户状态过滤
        - name: ids
          in: query
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: 多用户ID过滤，格式为?ids=1001&ids=1002&ids=1003
      responses:
        '200':
          description: 成功返回用户列表

关键注意点 #

• 两种规范都通过in: query明确标识查询参数，必填性、类型、枚举范围等属性是定义的核心部分。
• REST风格中常见的查询参数写法（比如键值对、多值数组、范围过滤等）都能通过规范配置实现，OpenAPI 3.0.3的style和explode参数还能适配不同的序列化格式。
• 只要你的定义符合这些规范，API文档工具、代码生成器都会正确识别，同时接口调用也完全兼容REST风格。

内容的提问来源于stack exchange，提问作者Rami Samara