Swagger-jsdoc 不引用 yaml 文件

Question

我的swagger-jsdoc和swagger-ui-express记录我的 Express 应用程序的设置显然无法读取或引用我指向它们的 YAML 文件

我仍在学习如何记录 API，并且我正在使用这篇文章https://www.codementor.io/peteradeoye/splitting-your-swagger-spec-into-multiple-files-in-a-node-project-nuprc0mej作为指导，但我无法复制所需的结果

这是我的 app.js

import 'core-js/stable';
import 'regenerator-runtime/runtime';
import express from 'express';
import bodyParser from 'body-parser';
import cors from 'cors';
import swaggerUI from 'swagger-ui-express';
import swaggerSpec from './config/swagger';
import allRoutes from './routes';


const app = express();

app.use('/api-docs', swaggerUI.serve, swaggerUI.setup(swaggerSpec));
app.use(cors());
app.use(bodyParser.urlencoded({
  extended: true,
}));
app.use(bodyParser.json());

allRoutes(app);

export default app;

这是我的招摇配置./config/swagger

const swaggerJSDoc = require('swagger-jsdoc');

const swaggerDefinition = {
  info: {
    title: 'REST API for Wayfarer', // Title of the documentation
    version: '1.0.0', // Version of the app
    description: 'This is the REST API for Wayfarer (a public bus transportation booking server.)', // short description of the app
  },
  host: 'localhost:3000', // the host or url of the app
  basePath: '/api/v1', // the basepath of your endpoint
};

// options for the swagger docs
const options = {
  // import swaggerDefinitions
  swaggerDefinition,
  // path to the API docs
  apis: ['./docs/**/*.yaml'],
};
// initialize swagger-jsdoc
export default swaggerJSDoc(options);

这是我引用的 yaml 之一./docs/user.yaml

paths:
  /auth/signup:                # path of the user from your endpoint
    post:                 # endpoint request type (post request)
      tags:               # Tag property
        - User            # Value of the tag
      summary: creates a new user
      produces:
      - application/json
      parameters:         # request parameters
      - in: body          # request body
        name: sign up     # name of the request, can be any name
        description: It enables a user to create an account
        required: false   # can also be true depending on user preference
        schema:           # Schema definition
          $ref: '#/definitions/signUp' 
      responses:          # server responses
        201:
          description: An object with user details
definitions:        # Schema definition for the request body
  signUp:
    type: object
        properties:
          username:
            type: string
          email:
            type: string
          password:
            type: string

当我尝试查看我的文档时，我希望看到显示一些信息，但我在浏览器中看到的是No operations defined in the spec. 我设法将问题范围缩小到

...
const options = {
  // import swaggerDefinitions
  swaggerDefinition,
  // path to the API docs
  apis: ['./docs/**/*.yaml'],
};
...

因为某些原因

...
apis: ['./docs/**/*.yaml'],
};
...

只是拒绝工作，我docs也重命名了我的文件夹，但这没有帮助。我将docs文件夹移至项目的根目录，错误消息更改为Error: TypeError: Cannot convert undefined or null to object

Answer 1

我遇到过同样的问题。尝试将 API 文档引用为绝对路径而不是相对路径。这对我有用。另外，请确保所有/任何根级属性也在文件内定义，swaggerDefinition而不是在.yaml文件内定义。如果您使用的是 OpenAPI 3.0 及以上版本，请确保也将其包含在内swaggerDefinition，如下所示：

const swaggerDefinition = {
  openapi: '3.0.2',
  info: {
    title: 'REST API for Wayfarer', // Title of the documentation
    version: '1.0.0', // Version of the app
    description: 'This is the REST API for Wayfarer (a public bus transportation booking server.)', // short description of the app
  },
  host: 'localhost:3000', // the host or url of the app
  basePath: '/api/v1', // the basepath of your endpoint
};