如何通过$ref引用本地文件定义OpenAPI组件，无需使用SwaggerHub？

完全可以用$ref引用本地文件来实现组件拆分，不需要依赖SwaggerHub这类第三方平台，这也是OpenAPI规范原生支持的功能。

核心实现方式 #

通过相对路径的$ref，把公共组件（Schema、参数、响应、安全规则等）单独存放在不同文件中，主API文件直接引用这些本地文件即可。

示例结构与代码 #

比如你的项目文件结构可以这样组织：

api-project/
├── openapi.yaml       # 主API定义文件
└── components/
    ├── parameters/
    │   └── userId.yaml
    └── schemas/
        ├── User.yaml
        └── Address.yaml

主文件openapi.yaml的写法：

openapi: 3.0.3
info:
  title: 用户管理API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: 获取单个用户
      parameters:
        - $ref: './components/parameters/userId.yaml' # 引用本地参数定义
      responses:
        '200':
          description: 成功返回用户数据
          content:
            application/json:
              schema:
                $ref: './components/schemas/User.yaml' # 引用本地Schema
components:
  # 也可以集中引用所有外部组件
  schemas:
    Address:
      $ref: './components/schemas/Address.yaml'

单个组件文件示例（components/schemas/User.yaml）：

type: object
properties:
  id:
    type: integer
    description: 用户ID
  name:
    type: string
    description: 用户姓名
  email:
    type: string
    format: email
    description: 用户邮箱
  address:
    $ref: '../schemas/Address.yaml' # 组件内部也可以互相引用

注意事项 #

• 路径正确性：$ref的路径是相对于当前文件的相对路径，层级要对应好，比如子目录里的文件引用同级其他文件，要用../回退层级。
• 工具兼容性：主流OpenAPI工具（Swagger UI、Redoc、OpenAPI Generator）都支持解析本地$ref，部分工具可能需要开启本地文件读取权限（比如Swagger UI在本地打开时可能需要浏览器允许）。
• 避免循环引用：组件之间互相引用时别搞成循环（比如A引用B，B又引用A），不然解析工具会报错。
• 合并文件：如果需要生成单个完整的OpenAPI文件用于发布或验证，可以用swagger-cli工具，执行命令：swagger-cli bundle openapi.yaml -o bundled-api.yaml -t yaml

内容的提问来源于stack exchange，提问作者Luca P.