如何在API文档UI中展示单记录GET端点的可选查询参数？

不管端点返回单条还是集合记录，只要带查询参数，都可以通过以下方式在API文档UI中清晰展示这些参数：

1. 基于OpenAPI（Swagger）规范的配置 #

如果用Swagger/OpenAPI维护文档，直接在paths下的对应GET端点中添加parameters字段，明确每个查询参数的属性：

• 标记参数的in为query（表明是查询参数）
• 填写name（如deleted、user）
• 设required为false（因为是可选参数）
• 在description里写清参数作用和可选值：比如deleted可写控制是否显示已删除记录，可选值：show（显示）、hide（隐藏，默认）；user可写按用户ID过滤，仅返回该用户关联的这条产品记录
• 补充schema定义参数类型，比如user设为integer类型

示例配置片段：

paths:
  /product/{id}:
    get:
      summary: 获取单条产品记录
      description: 根据产品ID查询单条记录，支持可选筛选条件
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: 产品ID
        - name: deleted
          in: query
          required: false
          schema:
            type: string
            enum: [show, hide]
          description: 控制是否显示已删除记录，默认值为hide
        - name: user
          in: query
          required: false
          schema:
            type: integer
          description: 按用户ID过滤，仅返回该用户关联的此产品记录
      responses:
        '200':
          description: 成功获取单条产品记录

配置完成后，Swagger UI会在端点详情的「Parameters」区域展示这些查询参数，和路径参数明确区分，描述清晰可见。

2. Postman文档配置 #

如果用Postman管理API：

• 打开对应请求的「Params」标签，添加deleted和user参数
• 在每个参数的「Description」栏填写说明，比如deleted写显示/隐藏已删除记录，可选值show/hide，user写按用户ID筛选关联记录
• 标记参数为「Optional」（可选）
• 保存后，Postman的文档视图会自动展示这些参数的名称、类型、描述和可选状态

3. 自定义API文档UI #

如果是自研的文档页面：

• 在端点详情区域单独增加「查询参数」板块，用列表形式展示每个参数：
  • 列出参数名、类型、是否可选、描述及可选值（如有）
• 搭配示例URI（比如/product/123?deleted=show&user=1）直观展示参数用法

关键注意点 #

• 明确区分路径参数（如{id}）和查询参数，避免混淆
• 每个参数的描述要精准，说明作用、可选值（如有）和默认行为
• 哪怕是单条记录的端点，只要有查询参数，就单独归类展示，不要和路径参数混在一起

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