Swagger 无法使用 Yaml 文件找到用户架构

Question

初学者在这里使用 swagger。我尝试创建一个简单的端点文档。但我无法弄清楚我的架构类型有什么问题。

我首先创建文件夹结构：在我的根 src 中，我有打字稿格式的 swagger 配置文件：

• 我使用路径模块引用了 API 和 Schame 路径。

import swaggerJSDoc from "swagger-jsdoc";
import path from 'path';

const userSchemaPath = path.join(__dirname, 'middlewares', 'validators', 'userSignup.swagger.yaml');
const userRouter = path.join(__dirname, 'routes', 'user.swagger.yaml');


const options: swaggerJSDoc.Options = {
    definition: {
        openapi:    '3.0.0',
        info: {
            title:  'Chat app with Sockets.io and HTTP',
            version: '1.0',
            contact: {
                email: 'sasdansss***iel9@***.com',
                name: 'Daniel Mihai'
            }
        },
        servers: [
            {
                url: 'http://localhost:3001',
                description: 'Local env server. Localhsot...'
            }
        ]
    },

    //Array of API routes
    apis: [userRouter, userSchemaPath]
}


const swaggerSpec = swaggerJSDoc(options);
export default swaggerSpec;

接下来，在路由器中，我开始为用户构建路由器端点的 yaml。

# User setup...
paths:
  /api/user:
    post:
      tags:
        - Users
      summary: Signup user. Create an account for the Chat application
      description: User is prompted to create an account for the application. User is required to use an unique email for the account.
      operationId: createUser
      requestBody:
        description: Fill all the fields and use a POST request /api/user to create a user.
        content: 
          application/json:
            schema: 
              $ref: '../middlewares/validators/userSignup.swagger.yaml'
            required: true
      responses:
        '201': 
          description: User created successfully
        '400':
          description: Invalid parameters provided. Zod validator responses
        '500':
          description: Something went wrong with the server. Or email duplicate error

此处查找架构时出错... 我使用摩根记录器并收到参考模式的 404 错误...我不明白它出了什么问题，因为我没有得到任何语法错误。我还检查了 ChatGPT，它向我指出了我已经检查过的内容（检查路径）...

::1 - - [06/Feb/2024:14:41:13 +0000] "GET /middlewares/validators/userSignup.swagger.yaml HTTP/1.1" 404 30

接下来，我为 zod 验证器构建架构：

components:
  schemas:
    UserSchema:
      type: object
      properties:
        email:
          type: string
          description: Unique email required to create an account 
          example: [email protected]
        firstName:
          type: string
          description: first name 
          example: Daniel
        lastName:
          type: string
          description: last name 
          example: Michael
        password:
          type: string
          description: password will be hashed 
          example: MyPassword

其他 localhsot swagger 规格： 我没有看到参数：

我也没有看到架构：

但是，在屏幕页面的底部，该架构有效：

Answer 1

解决了。显然对yaml文件的引用是由配置文件完成的......

因为在我的配置文件中我使用路径来引用该文件，所以在参考中我更正了以下内容：

$ref: '#/components/schemas/UserSchema'

因此，根据我的理解，引用正在查找我的配置文件中 APIS 数组中已指定的文件

apis: [userRouter, userSchemaPath]

参考将查找组件和模式：

components:
  schemas:
    UserSchema:
      type: object
      properties: