使用Swagger $ref引用路径时出现basePath未定义错误求助

问题场景 #

拆分Swagger API文档到多个YAML文件时，在main.yaml中通过$ref引用user.yaml出现如下错误：

Could not resolve reference: Tried to resolve a relative URL, without having a basePath. path: 'user.yaml' basePath: 'undefined'

尝试多种路径写法均无效，相关配置文件如下：

server.js #

const swaggerOptions = {
  swaggerDefinition: {
    openapi: '3.0.0',
    info: {
      title: "API",
      version: "1.0.0",
      description: "The API",
      contact: {
        name: "name"
      },
    },
    servers: [
      {
        url: "http://localhost:5000/api/"
      },
    ],
  },
  basePath: "/",
  apis: [
    "./swagger/main.yaml",
  ]
};

const swaggerDocs = swaggerJSDoc(swaggerOptions);
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerDocs));

main.yaml #

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: apikey
paths:
  /user:
    $ref: "user.yaml" # 尝试过多种路径写法均无效

user.yaml #

get:
  summary: "Get user by ID"
  parameters:
    - in: query
      name: id
      required: true
      schema:
        type: integer
  responses:
    "200":
      description: "Successful response"
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
  security:
    - ApiKeyAuth: []

解决方法 #

问题根源在于swagger-jsdoc需要加载所有涉及的YAML文件才能解析相对引用，同时要保证路径写法正确。

步骤1：将所有YAML文件加入apis数组 #

在server.js的apis列表中添加user.yaml的路径，让swagger-jsdoc能加载该文件：

apis: [
  "./swagger/main.yaml",
  "./swagger/user.yaml" // 添加此路径
]

步骤2：修正main.yaml中的$ref路径 #

确保$ref使用相对于main.yaml的正确相对路径（如果两个文件在同一目录下，写法如下）：

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

可选优化：规范user.yaml结构 #

如果希望引用更清晰，可以调整user.yaml为完整的路径结构，这样引用时可以精确指向具体操作：

调整后的user.yaml

paths:
  /user:
    get:
      summary: "Get user by ID"
      parameters:
        - in: query
          name: id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: "Successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
      security:
        - ApiKeyAuth: []

对应的main.yaml引用写法

paths:
  /user:
    $ref: './user.yaml#/paths/~1user'

验证 #

重启服务后访问/api-docs，即可正常加载拆分后的API文档，不再出现引用错误。

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