使用swagger-ui-express时Bearer Token授权失败问题及解决

问题描述 #

在Node.js项目中集成Swagger UI时遇到Token认证异常：

• Postman测试需Token认证的接口失败，无法正常在请求头传入Token
• 已在swagger.js中配置securitySchemes及BearerAuth规则，Swagger UI上显示认证图标，但测试带认证的接口时返回UnauthorizedError：未找到授权Token
• 无需认证的接口在Swagger UI中测试响应正常

错误配置示例 #

swagger.js 错误配置 #

const swaggerJsdoc = require("swagger-jsdoc");

// swagger options for API documention
const options = {
  definition: {
    openapi: "3.0.3",
    info: {
      servers: [
        {
          url: "http://localhost:3020",
        },
      ],
    },
    basePath: "/social",
    tags: [
      { name: "Auth", description: "Social Auth APIs" },
      { name: "Content", description: "Social Content APIs" },
    ],
    schemes: ["http"],
    consumes: ["application/json"],
    produces: ["application/json"],
  },
  // 错误位置：components定义在definition外部
  components: {
    securitySchemes: {
      BearerAuth: {
        type: "http",
        scheme: "bearer",
      },
    },
  },
  apis: ["./routes/*.js"],
};

const specs = swaggerJsdoc(options);

module.exports = {
  specs,
};

路由认证配置示例 #

/**
 * @swagger
 * /social/content/:
 *   get:
 *     description: retrieves the top level post for the current week selected by the coach for the current team
 *     security:
 *       - BearerAuth: []
 *     tags:
 *       - Content
 *     responses:
 *       200:
 *         description: Retrieved post success
 *       400:
 *         description: Bad request error
 *       401:
 *         description: Access token is missing or invalid
 *       500:
 *         description: Internal server error
 */

index.js Swagger配置 #

// swagger libs
const swaggerUi = require("swagger-ui-express");
const swaggerOptions = require("./utils/swagger");

// swagger docs
app.use(
  "/social/api-docs",
  swaggerUi.serve,
  swaggerUi.setup(swaggerOptions.specs, {
    explorer: true,
  })
);

解决方案 #

将components对象移至definition对象内部，修正后的swagger.js配置如下：

const swaggerJsdoc = require("swagger-jsdoc");

// swagger options for API documention
const options = {
  definition: {
    openapi: "3.0.3",
    info: {
      servers: [
        {
          url: "http://localhost:3020",
        },
      ],
    },
    basePath: "/social",
    tags: [
      { name: "Auth", description: "Social Auth APIs" },
      { name: "Content", description: "Social Content APIs" },
    ],
    schemes: ["http"],
    consumes: ["application/json"],
    produces: ["application/json"],
    // 修正：components移到definition内部
    components: {
      securitySchemes: {
        BearerAuth: {
          type: "http",
          scheme: "bearer",
        },
      },
    },
  },
  apis: ["./routes/*.js"],
};

const specs = swaggerJsdoc(options);

module.exports = {
  specs,
};

原因说明 #

OpenAPI 3.0规范要求components作为OpenAPI文档根对象（即definition配置的对象）的直接属性，之前将components定义在definition外部，导致Swagger无法正确识别BearerAuth安全方案，进而无法将用户输入的Token正确注入请求头，最终触发认证失败错误。

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