Swagger无法通过YAML文件找到User Schema问题求助

核心问题分析 #

1. $ref路径错误：你用文件相对路径../middlewares/validators/userSignup.swagger.yaml作为引用，Swagger UI会从浏览器端发起HTTP请求获取这个文件，但你的服务器并未将这些YAML文件配置为静态资源，所以返回404。
2. Swagger JSDoc合并逻辑误解：swagger-jsdoc会把apis数组中所有文件的内容合并到最终的OpenAPI定义里，正确的引用方式应该指向合并后的components节点，而非原文件路径。
3. requestBody的required属性位置错误：你把required: true放在了schema同级，不符合OpenAPI规范，应该作为requestBody的直接属性。

具体修复步骤 #

1. 修正用户路由YAML的$ref与required位置

修改user.swagger.yaml中的requestBody部分：

requestBody:
  description: Fill all the fields and use a POST request /api/user to create a user.
  required: true  # 移至此处，作为requestBody的直接属性
  content: 
    application/json:
      schema: 
        $ref: '#/components/schemas/UserSchema'  # 引用合并后的组件节点

2. 验证swagger-jsdoc的文件加载

你的TS配置中已通过path.join正确加载Schema和路由文件，这部分无需修改，但可以添加日志确认components是否被正确合并：

const swaggerSpec = swaggerJSDoc(options);
console.log(JSON.stringify(swaggerSpec.components, null, 2)); // 检查输出是否包含UserSchema
export default swaggerSpec;

3. 确保Swagger UI正确加载生成的Spec

如果通过Express等框架挂载Swagger UI，确保直接使用生成的swaggerSpec，而非加载单独YAML文件。示例：

import swaggerUi from 'swagger-ui-express';
import swaggerSpec from './swagger-config';

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

修复后效果 #

• Morgan的404日志会消失，不再请求外部YAML文件
• Swagger UI中会正常显示请求体的Schema结构和必填标识
• 页面底部的Schema组件会和接口的请求体引用保持一致

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