Node.js中Swagger UI未将指定Header加入请求的问题

测试用户登出接口时，发现通过Bearer Token携带的Authorization Header未被添加到Swagger UI发起的实际请求中，尽管接口YAML配置里已经明确定义了该Header，但始终不生效。

相关配置 #

1. Swagger接口YAML配置 #

/**
 * @swagger
 * /api/v1/users/auth/logout:
 *   post:
 *     tags:
 *       - Logout
 *     summary: Logout user
 *     description: Logout user from the system
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               phoneNumber:
 *                 type: string
 *                 description: User phone number
 *                 example: +201026984193
 *             required:
 *               - phoneNumber
 *     parameters:
 *       - in: header
 *         name: Authorization
 *         description: Bearer token for authentication
 *         required: true
 *         schema:
 *           type: string
 *         example: Bearer ERxoQss46UzGt0SAO0oZO7DykNT4KMvlKqJFcwctFt5DrjyBgCpi9l8H54SuoFlU
 *     responses:
 *       '400':
 *         description: Phone number is required
 *       '401':
 *         description: Phone number is not valid
 *       '404':
 *         description: User not found
 *       '204':
 *         description: User logged out successfully
 *       '409':
 *         description: Missing token
 *       '403':
 *         description: Unauthorized
 *       '406':
 *         description: Missing token and/or phoneNumber
 *       '405':
 *         description: Unauthorized
 *       '500':
 *         description: Internal server error. Something went wrong on the server.
 *       '429':
 *         description: Too many auth requests, please try again later.
 */

2. Swagger配置文件代码 #

const swaggerJsdoc = require("swagger-jsdoc");
const swaggerUi = require("swagger-ui-express");
const ip = require("ip");
const fs = require("fs");
require("dotenv").config();

const options = {
    definition: {
        openapi: "3.0.0",
        info: {
            title: "",
            description: "",
            version: "1.0.0",
        },
        servers: [
            {
                // url: `http://${ip.address()}:${process.env.PORT || 3000}`,
                url: `http://localhost:${process.env.PORT || 3000}`,
            },
        ],
        security: [{ Authorization: [] }],
    },
    apis: ["./routes/*.js"],
    customCss: `
        .swagger-ui .topbar-wrapper svg {
            display: none;
        }
    `,
};
const swaggerSpec = swaggerJsdoc(options);
const customCss = fs.readFileSync(process.cwd() + "/swagger.css", "utf8");

function swaggerDocs(app, port) {
    app.use(
        "/docs",
        swaggerUi.serve,
        swaggerUi.setup(swaggerSpec, { customCss })
    );
}
module.exports = swaggerDocs;

解决方案 #

1. 补充Security Scheme定义 #

当前配置里的security: [{ Authorization: [] }]缺少对应的安全方案说明，Swagger UI无法识别该参数的格式。需要在OpenAPI定义的components节点下添加securitySchemes配置：

修改Swagger配置文件中的options.definition部分：

const options = {
    definition: {
        openapi: "3.0.0",
        info: {
            title: "",
            description: "",
            version: "1.0.0",
        },
        servers: [
            {
                url: `http://localhost:${process.env.PORT || 3000}`,
            },
        ],
        components: {
            securitySchemes: {
                Authorization: {
                    type: "http",
                    scheme: "bearer",
                    bearerFormat: "JWT" // 可选，用于说明Token格式
                }
            }
        },
        security: [{ Authorization: [] }],
    },
    // 其余配置保持不变
};

2. 移除接口级别的Header参数定义 #

全局安全配置生效后，Swagger UI会自动生成Token输入框，此时接口YAML中单独定义的parameters会和全局配置冲突，建议移除接口里的Header参数定义：

修改后的接口YAML：

/**
 * @swagger
 * /api/v1/users/auth/logout:
 *   post:
 *     tags:
 *       - Logout
 *     summary: Logout user
 *     description: Logout user from the system
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               phoneNumber:
 *                 type: string
 *                 description: User phone number
 *                 example: +201026984193
 *             required:
 *               - phoneNumber
 *     responses:
 *       '400':
 *         description: Phone number is required
 *       '401':
 *         description: Phone number is not valid
 *       '404':
 *         description: User not found
 *       '204':
 *         description: User logged out successfully
 *       '409':
 *         description: Missing token
 *       '403':
 *         description: Unauthorized
 *       '406':
 *         description: Missing token and/or phoneNumber
 *       '405':
 *         description: Unauthorized
 *       '500':
 *         description: Internal server error. Something went wrong on the server.
 *       '429':
 *         description: Too many auth requests, please try again later.
 */

3. 验证配置效果 #

重启服务后，Swagger UI顶部会出现Authorize按钮，点击后输入格式为Bearer <你的Token>的内容，之后发起的所有请求都会自动携带Authorization Header。如果仅需单个接口生效，可移除全局security配置，在接口级别添加security: [{ Authorization: [] }]。

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