基于OpenAPI 3.0规范，如何用查询参数实现升降序排序？

一、指定asc/desc排序规则的常见方案（符合OpenAPI 3.0规范） #

方案1：字段前缀符号区分顺序（简洁型） #

最常用的方式是给排序字段添加前缀符号：用负号-表示降序（desc），无符号默认表示升序（asc），多个字段用逗号分隔。示例：

• 按id升序、name升序排序：GET /users?sort=id,name
• 按id降序、name升序排序：GET /users?sort=-id,name

对应OpenAPI 3.0的参数定义示例：

paths:
  /users:
    get:
      parameters:
        - name: sort
          in: query
          description: 排序规则，格式为「字段名（升序）」或「-字段名（降序）」，多字段用逗号分隔
          required: false
          schema:
            type: string
            # 用正则约束格式，也可替换为enum限定允许的排序字段
            pattern: '^(-?[a-zA-Z0-9]+)(,-?[a-zA-Z0-9]+)*$'
            example: '-id,name'

方案2：拆分排序字段与顺序（直观型） #

如果需要更明确的语义，可拆分出两个查询参数：sortBy指定排序字段，sortOrder对应每个字段的排序顺序，两者通过逗号一一对应。示例：

• 按id降序、name升序排序：GET /users?sortBy=id,name&sortOrder=desc,asc

对应OpenAPI 3.0的参数定义示例：

paths:
  /users:
    get:
      parameters:
        - name: sortBy
          in: query
          description: 排序字段，多字段用逗号分隔
          required: false
          schema:
            type: string
            enum: [id, name, email] # 限定允许的排序字段
            example: 'id,name'
        - name: sortOrder
          in: query
          description: 对应sortBy的排序顺序，多字段用逗号分隔，默认升序（asc）
          required: false
          schema:
            type: string
            enum: [asc, desc]
            example: 'desc,asc'

两种方案均符合OpenAPI 3.0规范，可根据团队的语义偏好选择：方案1更简洁，方案2对新手更友好。

二、GET方法是否适用于排序场景？ #

完全适用。

排序操作属于对资源查询结果的格式化处理，不会修改服务器端的用户数据，完全契合GET方法的核心语义：

1. 幂等性：重复执行相同的GET排序请求，返回结果一致（除非服务器数据更新）；
2. 无副作用：不会改变服务器状态；
3. 可缓存：GET请求可被浏览器、CDN等缓存，提升后续请求性能。

因此用GET方法传递排序参数是RESTful设计的常规做法。

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