环境配置

本章节将指导你完成开发环境的搭建，确保所有工具都能正常工作。

🎯 系统要求

操作系统

Windows 10/11
macOS 10.15+
Linux (Ubuntu 18.04+ / CentOS 7+)

软件要求

Node.js 16.0+（推荐 18.0+）
npm 7.0+ 或 yarn 1.22+
Git 2.0+

📦 安装 Node.js

Windows

使用官方安装包使用 Chocolatey使用 winget

powershell

# 1. 访问 https://nodejs.org
# 2. 下载 LTS 版本
# 3. 运行安装程序

powershell

# 安装 Chocolatey（如果还没有）
Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

# 安装 Node.js
choco install nodejs

powershell

# Windows 10+ 自带
winget install OpenJS.NodeJS

macOS

使用官方安装包使用 Homebrew使用 MacPorts

bash

# 访问 https://nodejs.org 下载安装

bash

# 安装 Homebrew（如果还没有）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js
brew install node

bash

sudo port install nodejs18

Linux

Ubuntu/DebianCentOS/RHEL/Fedora使用 nvm (推荐)

bash

# 使用 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# 或使用 snap
sudo snap install node --classic

bash

# 使用 NodeSource 仓库
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo yum install nodejs npm

# 或使用 dnf (Fedora)
sudo dnf install nodejs npm

bash

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载终端或执行
source ~/.bashrc

# 安装最新 LTS 版本
nvm install --lts
nvm use --lts

✅ 验证安装

bash

# 检查 Node.js 版本
node --version
# 应该显示 v18.x.x 或更高

# 检查 npm 版本
npm --version
# 应该显示 8.x.x 或更高

# 检查全局包位置
npm root -g

🛠️ 安装工具

全局安装推荐工具

bash

# OpenAPI Generator CLI
npm install -g @openapitools/openapi-generator-cli

# Redocly CLI
npm install -g @redocly/cli

# 可选：其他实用工具
npm install -g serve          # 静态文件服务器
npm install -g http-server    # 另一个静态文件服务器
npm install -g yaml-cli       # YAML 处理工具

验证工具安装

bash

# 检查 OpenAPI Generator
npx @openapitools/openapi-generator-cli version

# 检查 Redocly CLI
npx @redocly/cli --version

# 列出已安装的全局包
npm list -g --depth=0

📁 项目结构

创建项目结构

bash

#!/bin/bash
# setup-project.sh

PROJECT_NAME=${1:-"my-api-project"}

echo "📁 Creating project structure: $PROJECT_NAME"

mkdir -p "$PROJECT_NAME"/{api/{components/{schemas,responses,parameters},paths},generated/{clients/{typescript,java,python},servers/spring},docs,scripts,configs}

cd "$PROJECT_NAME"

# 创建 .gitignore
cat > .gitignore << 'EOF'
# Generated files
generated/
docs/
*.bundled.yaml
*.resolved.yaml

# Node modules
node_modules/

# IDE files
.vscode/
.idea/

# OS files
.DS_Store
Thumbs.db

# Logs
*.log
npm-debug.log*

# Environment variables
.env
.env.local
EOF

# 创建示例 OpenAPI 文件
cat > api/openapi.yaml << 'EOF'
openapi: 3.0.1
info:
  title: My API
  description: API description
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /health:
    get:
      summary: Health check
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "ok"
EOF

# 创建 README
cat > README.md << 'EOF'
# My API Project

This project contains OpenAPI specifications and generated client/server code.

## Quick Start

1. Install dependencies:
   ```bash
   npm install -g @openapitools/openapi-generator-cli @redocly/cli

Generate code:
bash
```
./scripts/generate-all.sh
```
1
View documentation:
bash
```
npx serve docs
```
1

Directory Structure

api/ - OpenAPI specifications
generated/ - Generated client and server code
docs/ - Generated documentation
scripts/ - Automation scripts
configs/ - Configuration files EOF

echo "✅ Project structure created successfully!" echo "📁 Project location: $(pwd)" echo "" echo "🚀 Next steps:" echo "1. cd $PROJECT_NAME" echo "2. Edit api/openapi.yaml" echo "3. Run: npx @redocly/cli lint api/openapi.yaml"


## ⚙️ IDE 配置

### VS Code

#### 推荐扩展

创建 `.vscode/extensions.json`：

```json
{
  "recommendations": [
    "redhat.vscode-yaml",
    "ms-vscode.vscode-json",
    "42crunch.vscode-openapi",
    "redocly.openapi-vs-code",
    "ms-vscode.vscode-typescript-next",
    "bradlc.vscode-tailwindcss"
  ]
}

工作区设置

创建 .vscode/settings.json：

json

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.json": [
      "api/**/*.yaml",
      "api/**/*.yml"
    ]
  },
  "files.associations": {
    "*.yaml": "yaml",
    "*.yml": "yaml"
  },
  "editor.formatOnSave": true,
  "yaml.format.enable": true,
  "redocly.OpenAPI-vs-code.useDefault": true
}

任务配置

创建 .vscode/tasks.json：

json

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Validate OpenAPI",
      "type": "shell",
      "command": "npx @redocly/cli lint api/openapi.yaml",
      "group": "test",
      "presentation": {
        "echo": true,
        "reveal": "always"
      }
    },
    {
      "label": "Preview Documentation",
      "type": "shell",
      "command": "npx @redocly/cli preview-docs api/openapi.yaml --port 3000",
      "group": "test",
      "isBackground": true
    },
    {
      "label": "Generate TypeScript Client",
      "type": "shell",
      "command": "npx @openapitools/openapi-generator-cli generate -i api/openapi.yaml -g typescript-fetch -o generated/clients/typescript",
      "group": "build"
    }
  ]
}

IntelliJ IDEA / WebStorm

配置文件关联

打开 Settings → Editor → File Types
找到 YAML 文件类型
添加模式：*.openapi.yaml、*.api.yaml

🔧 常用配置

npm 配置

bash

# 设置 npm 镜像（中国用户）
npm config set registry https://registry.npmmirror.com

# 设置全局包安装目录（可选）
npm config set prefix ~/.npm-global

# 查看当前配置
npm config list

环境变量

在 ~/.bashrc 或 ~/.zshrc 中添加：

bash

# Node.js 内存限制
export NODE_OPTIONS="--max-old-space-size=4096"

# npm 全局包路径（如果自定义了prefix）
export PATH=$PATH:~/.npm-global/bin

# OpenAPI Generator 版本锁定（可选）
export OPENAPI_GENERATOR_VERSION="6.6.0"

🐳 Docker 环境

如果你更喜欢使用 Docker：

创建 Dockerfile

dockerfile

FROM node:18-alpine

# 安装全局工具
RUN npm install -g @openapitools/openapi-generator-cli @redocly/cli

# 设置工作目录
WORKDIR /workspace

# 安装 Java（OpenAPI Generator 需要）
RUN apk add --no-cache openjdk11

CMD ["sh"]

使用 Docker

bash

# 构建镜像
docker build -t openapi-tools .

# 运行容器
docker run -it --rm -v $(pwd):/workspace openapi-tools

# 在容器内运行命令
npx @redocly/cli lint api/openapi.yaml

Docker Compose

创建 docker-compose.yml：

yaml

version: '3.8'
services:
  openapi-tools:
    build: .
    volumes:
      - .:/workspace
    working_dir: /workspace
    ports:
      - "3000:3000"  # 用于预览文档
    command: tail -f /dev/null  # 保持容器运行

🧪 验证环境

创建验证脚本 verify-setup.sh：

bash

#!/bin/bash

echo "🔍 Verifying development environment..."

# 检查 Node.js
if command -v node &> /dev/null; then
    NODE_VERSION=$(node -v)
    echo "✅ Node.js: $NODE_VERSION"
    
    # 检查版本是否足够新
    NODE_MAJOR=$(echo $NODE_VERSION | cut -d'.' -f1 | cut -d'v' -f2)
    if [ "$NODE_MAJOR" -lt 16 ]; then
        echo "⚠️  Warning: Node.js version should be 16 or higher"
    fi
else
    echo "❌ Node.js not found"
    exit 1
fi

# 检查 npm
if command -v npm &> /dev/null; then
    NPM_VERSION=$(npm -v)
    echo "✅ npm: $NPM_VERSION"
else
    echo "❌ npm not found"
    exit 1
fi

# 检查 OpenAPI Generator
if npx @openapitools/openapi-generator-cli version &> /dev/null; then
    OG_VERSION=$(npx @openapitools/openapi-generator-cli version)
    echo "✅ OpenAPI Generator: $OG_VERSION"
else
    echo "❌ OpenAPI Generator CLI not accessible"
    echo "💡 Try: npm install -g @openapitools/openapi-generator-cli"
fi

# 检查 Redocly CLI
if npx @redocly/cli --version &> /dev/null; then
    REDOCLY_VERSION=$(npx @redocly/cli --version)
    echo "✅ Redocly CLI: $REDOCLY_VERSION"
else
    echo "❌ Redocly CLI not accessible"
    echo "💡 Try: npm install -g @redocly/cli"
fi

# 检查 Java（OpenAPI Generator 需要）
if command -v java &> /dev/null; then
    JAVA_VERSION=$(java -version 2>&1 | head -n 1)
    echo "✅ Java: $JAVA_VERSION"
else
    echo "⚠️  Java not found (required for OpenAPI Generator)"
    echo "💡 Install Java 8 or higher"
fi

# 测试创建简单项目
echo ""
echo "🧪 Testing tool functionality..."

# 创建临时目录
TEST_DIR=$(mktemp -d)
cd "$TEST_DIR"

# 创建测试 API 文件
cat > test-api.yaml << 'EOF'
openapi: 3.0.1
info:
  title: Test API
  version: 1.0.0
paths:
  /test:
    get:
      responses:
        '200':
          description: OK
EOF

# 测试验证
if npx @redocly/cli lint test-api.yaml &> /dev/null; then
    echo "✅ OpenAPI validation works"
else
    echo "❌ OpenAPI validation failed"
fi

# 测试文档生成
if npx @redocly/cli build-docs test-api.yaml -o test-docs.html &> /dev/null; then
    echo "✅ Documentation generation works"
else
    echo "❌ Documentation generation failed"
fi

# 清理
cd - > /dev/null
rm -rf "$TEST_DIR"

echo ""
echo "🎉 Environment verification completed!"

运行验证：

bash

chmod +x verify-setup.sh
./verify-setup.sh

🚨 常见问题

Node.js 版本问题

bash

# 问题：Node.js 版本过低
# 解决：使用 nvm 管理版本
nvm install 18
nvm use 18
nvm alias default 18

权限问题

bash

# 问题：npm 全局安装权限错误
# 解决：配置 npm 前缀
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

网络问题

bash

# 问题：npm 安装缓慢
# 解决：使用国内镜像
npm config set registry https://registry.npmmirror.com

# 或使用 cnpm
npm install -g cnpm --registry=https://registry.npmmirror.com
cnpm install -g @openapitools/openapi-generator-cli

Java 环境问题

bash

# 问题：OpenAPI Generator 需要 Java
# 解决：安装 OpenJDK

# Ubuntu/Debian
sudo apt update
sudo apt install openjdk-11-jdk

# macOS
brew install openjdk@11

# Windows
# 下载并安装 OpenJDK：https://adoptopenjdk.net/

完成环境配置后，你就可以开始使用 OpenAPI 工具链了！

环境配置

🎯 系统要求

操作系统

软件要求

📦 安装 Node.js

Windows

macOS

Linux

✅ 验证安装

🛠️ 安装工具

全局安装推荐工具

验证工具安装

📁 项目结构

推荐的项目目录结构

创建项目结构

Directory Structure

工作区设置

任务配置

IntelliJ IDEA / WebStorm

推荐插件

配置文件关联

🔧 常用配置

npm 配置

环境变量

🐳 Docker 环境

创建 Dockerfile

使用 Docker

Docker Compose

🧪 验证环境

🚨 常见问题

Node.js 版本问题

权限问题

网络问题

Java 环境问题

环境配置 ​

🎯 系统要求 ​

操作系统 ​

软件要求 ​

📦 安装 Node.js ​

Windows ​

macOS ​

Linux ​

✅ 验证安装 ​

🛠️ 安装工具 ​

全局安装推荐工具 ​

验证工具安装 ​

📁 项目结构 ​

推荐的项目目录结构 ​

创建项目结构 ​

Directory Structure ​

工作区设置 ​

任务配置 ​

IntelliJ IDEA / WebStorm ​

推荐插件 ​

配置文件关联 ​

🔧 常用配置 ​

npm 配置 ​

环境变量 ​

🐳 Docker 环境 ​

创建 Dockerfile ​

使用 Docker ​

Docker Compose ​

🧪 验证环境 ​

🚨 常见问题 ​

Node.js 版本问题 ​

权限问题 ​

网络问题 ​

Java 环境问题 ​

环境配置

🎯 系统要求

操作系统

软件要求

📦 安装 Node.js

Windows

macOS

Linux

✅ 验证安装

🛠️ 安装工具

全局安装推荐工具

验证工具安装

📁 项目结构

推荐的项目目录结构

创建项目结构

Directory Structure

工作区设置

任务配置

IntelliJ IDEA / WebStorm

推荐插件

配置文件关联

🔧 常用配置

npm 配置

环境变量

🐳 Docker 环境

创建 Dockerfile

使用 Docker

Docker Compose

🧪 验证环境

🚨 常见问题

Node.js 版本问题

权限问题

网络问题

Java 环境问题