Express服务器Swagger文档不生效及TS配置问题咨询

一、「No Operations defined in spec!」报错原因及修复 #

• 配置缺失openapi版本声明
  swagger-jsdoc 6.x及以上版本要求在definition中明确指定openapi版本，否则会出现注解解析失败问题，需要补充配置：

const swaggerOptions: Options = {
   definition: {
      openapi: "3.0.0", // 补充这一行
      info: {
         title: "Project Nonya Documentation.",
         description: "Documentation for the Project Nonya API",
         contact: {
            name: "Joe Mama",
         },
         version: "6.9.0",
      },
   },
   apis: ["./routes/*.routes.ts"],
};

• 路由文件后缀匹配错误
  你配置的apis规则是./routes/*.routes.ts，但实际路由文件命名为testing.router.ts，后缀是.router.ts而非.routes.ts，规则无法匹配到对应文件，自然读不到注解。
  修复：把匹配规则修改为对应后缀，比如./src/routes/*.router.ts

• 相对路径解析错误
  你的docs.ts放在src目录下，如果项目启动入口在项目根目录（比如执行node dist/router.js或ts-node src/router.ts），相对路径./routes/会被解析为根目录下的routes文件夹，而非src下的routes文件夹，导致找不到文件。
  修复：把apis路径写全src层级，或者直接配置为绝对路径。

• Swagger注解与实际路由不匹配
  你注解里声明的是GET /接口，但实际定义的是POST /testing/:id接口，Swagger不会自动把注解和实际路由做关联，需要保证注解里的请求方法、路径和实际路由一致，修复示例：

/**
 * @swagger
 * /testing/{id}:
 *   post:
 *     description: 测试接口
 *     parameters:
 *       - name: id
 *         in: path
 *         required: true
 *         schema:
 *           type: string
 *     responses:
 *       200:
 *         description: 接口正常返回
 */
router.post("/testing/:id", testing);

二、后缀匹配问题解答 #

分两种场景处理：

• 开发环境用ts-node直接运行TS代码：需要匹配.ts后缀才能读到注解
• 生产环境编译为JS后运行：需要匹配.js后缀才能读到编译后文件中的注解
  最优配置是直接配置同时匹配两种后缀，开发和生产环境都可以生效：

apis: ["./src/routes/*.router.{ts,js}"],

如果编译后dist目录结构和src一致，也可以根据实际编译输出调整为匹配dist目录下的js文件。

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