使用swagger-ui-express时，如何在openapi.yaml中引用外部路径？

核心问题分析 #

你遇到的错误根源是子YAML文件结构不符合OpenAPI引用规则，且swagger-ui-express默认不会自动解析本地相对路径的$ref引用。

正确的模块化配置方式 #

1. 调整子文件结构（test.yaml）

让test.yaml直接以接口路径作为根节点，不要嵌套在自定义键下：

# doc/test.yaml
/test:
  get:
    summary: 测试接口
    responses:
      '200':
        description: 成功返回测试数据
        content:
          application/json:
            schema:
              type: object
              properties:
                msg:
                  type: string

2. 主文档（openapi.yaml）的引用方案

有两种可行的引用方式：

方案一：直接引用整个路径文件

在主文档的paths字段下直接引用子文件，合并后Swagger UI会自动加载该路径：

# doc/openapi.yaml
openapi: 3.0.0
info:
  title: 我的API文档
  version: 1.0.0
paths:
  $ref: './test.yaml'

方案二：单独引用特定路径

如果子文件包含多个路径，或者仅需引用单个路径，可直接指定（前提是子文件中路径为根节点）：

paths:
  /test:
    $ref: './test.yaml'

3. 确保Express代码正确加载合并文档

由于swagger-ui-express无法自动解析本地文件的相对引用，需要手动读取并合并YAML文件：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const yaml = require('yaml');
const fs = require('fs');
const path = require('path');

const app = express();

// 读取主文档
const mainDoc = yaml.parse(fs.readFileSync(path.join(__dirname, 'doc/openapi.yaml'), 'utf8'));
// 读取子文档并合并到主文档的paths中
const testDoc = yaml.parse(fs.readFileSync(path.join(__dirname, 'doc/test.yaml'), 'utf8'));
mainDoc.paths = { ...mainDoc.paths, ...testDoc };

// 挂载Swagger UI路由
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(mainDoc));

app.listen(3000, () => console.log('服务启动在3000端口'));

常见错误排查 #

• 不要将路径嵌套在test这类自定义键下，否则#/test指针会指向自定义键而非路径节点
• 确认相对路径书写正确（主、子文件同目录时，./test.yaml是正确写法）
• 避免使用$ref: './test.yaml#/~1test'这类URL编码写法，这不符合模块化路径的最佳实践

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