OpenAPI如何为带reviewStatus查询参数的接口配置权限？有哪些更优API设计？

OpenAPI本身不支持直接为单个查询参数绑定独立的security安全规则，你可以通过以下方式满足规范要求：

• 先定义两个权限范围：products:read:approved（普通用户默认权限）、products:read:all（管理员专属权限）
• 在接口定义中通过参数描述、响应说明补充权限约束逻辑，示例OpenAPI 3.0配置如下：

paths:
  /products:
    get:
      summary: 拉取商品列表
      parameters:
        - name: reviewStatus
          in: query
          description: 商品审核状态，仅管理员可传入waiting/rejected
          schema:
            type: string
            enum: [approved, waiting, rejected]
            default: approved
      security:
        - OAuth2:
            - products:read:approved
            - products:read:all
      responses:
        '200':
          description: 商品列表返回成功
        '401':
          description: 未授权，当普通用户请求reviewStatus为waiting/rejected时也会返回该状态码

实际的参数-权限匹配逻辑放在业务服务层实现即可，接口文档侧已经可以明确透出所有规则。

针对这种基于资源状态的权限隔离场景，更推荐将不同权限的资源入口拆分，从设计根源规避参数级权限校验的问题：

• 普通用户专属接口：GET /products/approved，仅返回审核通过的商品，权限要求为普通用户可访问
• 管理员专属接口：GET /admin/products，支持传入reviewStatus参数查询所有状态的商品，权限要求为管理员专属

该设计的优势：

• 权限直接绑定到接口路径，完全符合OpenAPI的安全规则配置逻辑，不需要额外补充自定义约束
• 接口职责清晰，同一个接口不会因调用者身份不同返回完全不同的结果，排查问题、做流量管控都更方便
• 权限校验可以前置到网关层完成，不需要进入业务层解析参数再判断，性能更高且不会出现权限漏判的问题

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