Swagger新手求助：如何实现嵌套路径将/user与/user/{id}归为一组？

嘿，没问题！Swagger（现在一般指OpenAPI规范）完全支持路径的嵌套展示，而且实现起来并不复杂，我给你梳理几种靠谱的方法：

方法一：依赖Swagger UI的自动分组（最简单） #

大多数现代版本的Swagger UI（3.x及以上）会自动识别具有共同前缀的路径，把它们折叠展示在同一个父路径下。比如你定义的/user和/user/{id}，UI默认就会把/user/{id}归到/user的分组里，点击就能展开查看。如果你的UI没自动这么做，大概率是版本太旧了，建议升级到最新版的Swagger UI试试。

方法二：用标签+扩展属性手动控制分组 #

如果自动分组不生效，或者你想更灵活地组织结构，可以给这两个API打上相同的标签，再用x-tagGroups扩展来构建层级：

openapi: 3.0.3
info:
  title: 用户管理API
  version: 1.0.0
tags:
  - name: 用户管理
    description: 所有用户相关操作集合
x-tagGroups:
  - name: 用户接口组
    tags:
      - 用户管理
paths:
  /user:
    get:
      tags:
        - 用户管理
      summary: 获取所有用户
      responses:
        '200':
          description: 成功返回用户列表
  /user/{id}:
    get:
      tags:
        - 用户管理
      summary: 根据ID获取单个用户
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功返回单个用户详情

配置后，Swagger UI会把这两个API归到同一个标签组下，呈现出类似嵌套的结构，逻辑上更清晰。

方法三：OpenAPI 3.1的结构化路径定义（最规范） #

如果你用的是OpenAPI 3.1版本，可以直接在父路径下引用子路径的定义，从语法层面实现嵌套：

openapi: 3.1.0
info:
  title: 用户管理API
  version: 1.0.0
paths:
  /user:
    get:
      summary: 获取所有用户
      responses:
        '200':
          description: 成功返回用户列表
    $ref: '#/components/pathItems/userById'
components:
  pathItems:
    userById:
      /{id}:
        get:
          summary: 根据ID获取单个用户
          parameters:
            - name: id
              in: path
              required: true
              schema:
                type: integer
          responses:
            '200':
              description: 成功返回单个用户详情

这种方式相当于把/user/{id}作为/user的子路径来定义，UI会自然展示成嵌套结构，也更符合API的层级逻辑。

另外提一句：如果还在使用旧版的Swagger 2.0，原生没有这么灵活的嵌套语法，但同样可以通过标签分组的方式实现类似的展示效果，核心思路还是把相关API归到同一个标签下。

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