Node.js中如何在swagger.yaml配置文件中使用环境变量？

我懂你为啥头疼——直接在swagger.yaml里写${process.env.VARNAME}这类语法根本不管用，毕竟Swagger本身并不支持直接读取Node.js的环境变量。不过别担心，咱们可以在加载YAML文件的环节做变量替换，完美解决这个问题，下面给你几个实用的方案：

方法一：使用js-yaml配合环境变量替换 #

这个方法的核心思路是：先把YAML文件当作纯文本读进来，手动替换里面的环境变量占位符，再解析成Swagger对象。

1. 首先安装依赖：

npm install js-yaml dotenv

2. 编写加载Swagger配置的代码：

// 先加载.env文件里的环境变量
require('dotenv').config();
const fs = require('fs');
const yaml = require('js-yaml');

// 读取swagger.yaml的原始内容
const swaggerRawContent = fs.readFileSync('./swagger.yaml', 'utf8');

// 替换所有形如${VAR_NAME}的占位符
const processedContent = swaggerRawContent.replace(
  /\${([^}]+)}/g,
  (match, varName) => {
    // 如果环境变量存在就替换，不存在就保留原占位符（也可以改成抛出错误）
    return process.env[varName] || match;
  }
);

// 解析处理后的内容为Swagger文档对象
const swaggerDocument = yaml.load(processedContent);

// 之后就可以把swaggerDocument传给swagger-ui-express等中间件使用

3. 对应的swagger.yaml写法：

openapi: 3.0.0
info:
  title: 我的API文档
  version: 1.0.0
servers:
  - url: ${API_BASE_URL}
    description: 生产环境服务器
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功返回用户列表

方法二：改用swagger-jsdoc（用JS定义Swagger配置） #

如果不想折腾YAML的变量替换，直接用JavaScript来写Swagger配置是更直接的方式——毕竟JS里可以直接访问process.env。

1. 安装依赖：

npm install swagger-jsdoc swagger-ui-express

2. 编写配置代码：

require('dotenv').config();
const swaggerJsdoc = require('swagger-jsdoc');

const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: '我的API文档',
      version: '1.0.0',
    },
    servers: [
      {
        url: process.env.API_BASE_URL,
        description: '生产环境服务器'
      }
    ]
  },
  apis: ['./routes/*.js'] // 指定你的路由文件路径，swagger-jsdoc会自动解析路由里的注释生成文档
};

const swaggerDocument = swaggerJsdoc(swaggerOptions);

这种方式完全绕开了YAML的变量问题，直接在JS里使用环境变量，非常省心。

方法三：Webpack场景用yaml-template-loader预处理 #

如果你的项目是用Webpack打包的，可以用专门的loader来预处理YAML文件，自动替换环境变量。

1. 安装依赖：

npm install yaml-template-loader yaml-loader --save-dev

2. 修改Webpack配置：

module.exports = {
  module: {
    rules: [
      {
        test: /swagger\.yaml$/,
        use: [
          'yaml-loader',
          {
            loader: 'yaml-template-loader',
            options: {
              data: process.env // 把环境变量传给loader作为替换数据源
            }
          }
        ]
      }
    ]
  }
};

3. swagger.yaml里的写法：

servers:
  - url: {{API_BASE_URL}} # 用双大括号作为占位符，具体格式看loader配置
    description: 生产环境服务器

总结 #

Swagger本身不支持直接解析Node.js的环境变量，所以必须在加载YAML文件的过程中完成变量替换，或者改用JS来定义Swagger配置。上面的几种方法可以根据你的项目场景来选择，其中方法一和方法二是最通用的。

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