OpenAPI Generator 安装配置

快速搭建 OpenAPI 代码生成环境

系统要求

基础要求

组件	最低版本	推荐版本	说明
Java	8	11+	OpenAPI Generator 运行环境
Node.js	14	18+	npm 包管理器
Git	2.0	最新	版本控制

可选组件

Docker: 容器化运行（推荐）
Maven/Gradle: Java 项目构建
Python: Python 生成器支持

安装方式

方式 1: npm 安装（推荐）

最简单的安装方式，适合大多数场景：

bash

# 全局安装
npm install -g @openapitools/openapi-generator-cli

# 验证安装
openapi-generator-cli version

# 设置特定版本（可选）
openapi-generator-cli version-manager set 7.0.0

项目级安装

bash

# 在项目中安装
npm install --save-dev @openapitools/openapi-generator-cli

# package.json 中添加脚本
{
  "scripts": {
    "generate": "openapi-generator-cli generate",
    "generate:client": "openapi-generator-cli generate -i ./api/openapi.yaml -g typescript-axios -o ./src/api/client",
    "generate:server": "openapi-generator-cli generate -i ./api/openapi.yaml -g spring -o ./src/api/server"
  }
}

方式 2: Docker 安装

使用 Docker 运行，无需安装 Java：

bash

# 拉取最新镜像
docker pull openapitools/openapi-generator-cli:latest

# 运行生成器
docker run --rm \
  -v ${PWD}:/local \
  openapitools/openapi-generator-cli generate \
  -i /local/api/openapi.yaml \
  -g typescript-axios \
  -o /local/generated

# 创建别名简化使用
alias openapi-generator="docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli"

Docker Compose 配置

yaml

# docker-compose.yml
version: '3.8'
services:
  openapi-generator:
    image: openapitools/openapi-generator-cli:latest
    volumes:
      - ./:/local
    working_dir: /local
    command: generate -i /local/api/openapi.yaml -g spring -o /local/generated

方式 3: Homebrew 安装（macOS/Linux）

bash

# 安装
brew install openapi-generator

# 验证
openapi-generator version

# 更新
brew upgrade openapi-generator

方式 4: 直接下载 JAR

bash

# 下载最新版本
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.0.0/openapi-generator-cli-7.0.0.jar \
  -O openapi-generator-cli.jar

# 运行
java -jar openapi-generator-cli.jar version

# 创建启动脚本
echo 'java -jar /path/to/openapi-generator-cli.jar "$@"' > /usr/local/bin/openapi-generator
chmod +x /usr/local/bin/openapi-generator

配置文件

全局配置

创建 .openapitools.json 配置文件：

json

{
  "$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
  "spaces": 2,
  "generator-cli": {
    "version": "7.0.0",
    "repository": {
      "downloadUrl": "https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/${versionName}/openapi-generator-cli-${versionName}.jar"
    },
    "generators": {
      "v1": {
        "generatorName": "typescript-axios",
        "output": "./generated/v1",
        "inputSpec": "./api/v1/openapi.yaml",
        "additionalProperties": {
          "npmName": "@company/api-client-v1",
          "supportsES6": true,
          "withInterfaces": true
        }
      },
      "v2": {
        "generatorName": "spring",
        "output": "./generated/v2",
        "inputSpec": "./api/v2/openapi.yaml",
        "additionalProperties": {
          "basePackage": "com.company.api",
          "modelPackage": "com.company.api.model",
          "apiPackage": "com.company.api.controller"
        }
      }
    }
  }
}

项目配置

创建 openapi-generator-config.yaml：

yaml

# 客户端生成配置
typescript-axios:
  generatorName: typescript-axios
  outputDir: ./src/generated/client
  inputSpec: ./api/openapi.yaml
  additionalProperties:
    npmName: "@company/api-client"
    npmVersion: "1.0.0"
    supportsES6: true
    withInterfaces: true
    useSingleRequestParameter: true
  globalProperties:
    modelDocs: false
    apiDocs: false
  typeMappings:
    DateTime: Date
    Date: Date

# 服务端生成配置  
spring-boot:
  generatorName: spring
  outputDir: ./src/generated/server
  inputSpec: ./api/openapi.yaml
  additionalProperties:
    basePackage: com.company.api
    configPackage: com.company.api.config
    title: Company API
    java8: true
    dateLibrary: java8
    interfaceOnly: true
    useTags: true

环境变量配置

bash

# ~/.bashrc 或 ~/.zshrc

# OpenAPI Generator 配置
export OPENAPI_GENERATOR_VERSION=7.0.0
export JAVA_OPTS="-Xmx1024M -DloggerPath=conf/log4j.properties"

# 代理设置（如需要）
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# 自定义模板路径
export OPENAPI_GENERATOR_TEMPLATE_DIR=/path/to/custom/templates

IDE 集成

VS Code 扩展

安装推荐扩展：

json

// .vscode/extensions.json
{
  "recommendations": [
    "42crunch.vscode-openapi",
    "mermade.openapi-lint",
    "arjun.swagger-viewer",
    "philosowaffle.openapi-designer"
  ]
}

配置任务：

json

// .vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Generate API Client",
      "type": "shell",
      "command": "openapi-generator-cli",
      "args": [
        "generate",
        "-i", "${workspaceFolder}/api/openapi.yaml",
        "-g", "typescript-axios",
        "-o", "${workspaceFolder}/generated/client"
      ],
      "group": {
        "kind": "build",
        "isDefault": true
      },
      "problemMatcher": []
    }
  ]
}

IntelliJ IDEA 配置

安装 OpenAPI Generator 插件
配置外部工具：

xml

<!-- .idea/externalTools.xml -->
<toolSet name="OpenAPI">
  <tool name="Generate Client" showInMainMenu="true">
    <exec>
      <option name="COMMAND" value="openapi-generator-cli" />
      <option name="PARAMETERS" value="generate -i $ProjectFileDir$/api/openapi.yaml -g typescript-axios -o $ProjectFileDir$/generated" />
      <option name="WORKING_DIRECTORY" value="$ProjectFileDir$" />
    </exec>
  </tool>
</toolSet>

验证安装

基础验证脚本

bash

#!/bin/bash
# verify-installation.sh

echo "🔍 检查 OpenAPI Generator 安装..."

# 检查 Java
if command -v java &> /dev/null; then
    echo "✅ Java 已安装: $(java -version 2>&1 | head -n 1)"
else
    echo "❌ Java 未安装"
    exit 1
fi

# 检查 OpenAPI Generator
if command -v openapi-generator-cli &> /dev/null; then
    echo "✅ OpenAPI Generator CLI 已安装: $(openapi-generator-cli version)"
elif command -v openapi-generator &> /dev/null; then
    echo "✅ OpenAPI Generator 已安装: $(openapi-generator version)"
else
    echo "❌ OpenAPI Generator 未安装"
    exit 1
fi

# 测试生成
echo "🧪 测试代码生成..."
cat > test-api.yaml << EOF
openapi: 3.0.0
info:
  title: Test API
  version: 1.0.0
paths:
  /test:
    get:
      summary: Test endpoint
      responses:
        '200':
          description: Success
EOF

openapi-generator-cli generate \
  -i test-api.yaml \
  -g typescript-axios \
  -o test-output \
  --skip-validate-spec

if [ -d "test-output" ]; then
    echo "✅ 代码生成成功"
    rm -rf test-output test-api.yaml
else
    echo "❌ 代码生成失败"
    exit 1
fi

echo "🎉 安装验证完成！"

生成器列表

查看所有可用的生成器：

bash

# 列出所有生成器
openapi-generator-cli list

# 查看特定生成器的帮助
openapi-generator-cli help generate typescript-axios

# 查看生成器配置选项
openapi-generator-cli config-help -g typescript-axios

常见问题

1. Java 版本问题

bash

# 错误：Unsupported major.minor version
# 解决：安装正确的 Java 版本
sdk install java 11.0.12-open  # 使用 SDKMAN
# 或
brew install openjdk@11

2. 内存不足

bash

# 增加 JVM 内存
export JAVA_OPTS="-Xmx2048M"

# 或在命令中指定
java -Xmx2048M -jar openapi-generator-cli.jar generate ...

3. 代理问题

bash

# 配置 HTTP 代理
export HTTP_PROXY=http://proxy:8080
export HTTPS_PROXY=http://proxy:8080

# npm 代理
npm config set proxy http://proxy:8080
npm config set https-proxy http://proxy:8080

4. 权限问题

bash

# npm 全局安装权限
sudo npm install -g @openapitools/openapi-generator-cli

# 或使用 npx（无需全局安装）
npx @openapitools/openapi-generator-cli generate ...

升级指南

检查更新

bash

# npm 版本
npm outdated -g @openapitools/openapi-generator-cli

# 查看可用版本
npm view @openapitools/openapi-generator-cli versions --json

升级步骤

bash

# 1. 备份当前配置
cp .openapitools.json .openapitools.json.backup

# 2. 升级到最新版本
npm update -g @openapitools/openapi-generator-cli

# 3. 或升级到特定版本
openapi-generator-cli version-manager set 7.1.0

# 4. 验证升级
openapi-generator-cli version

# 5. 测试生成
npm run generate

性能优化

1. 并行生成

json

// package.json
{
  "scripts": {
    "generate:all": "npm-run-all --parallel generate:*",
    "generate:client": "openapi-generator-cli generate -c client-config.yaml",
    "generate:server": "openapi-generator-cli generate -c server-config.yaml",
    "generate:docs": "openapi-generator-cli generate -c docs-config.yaml"
  }
}

2. 缓存配置

bash

# 启用 Maven 缓存
export MAVEN_OPTS="-Dmaven.repo.local=./.m2/repository"

# Docker 层缓存
docker build --cache-from openapitools/openapi-generator-cli:latest .

3. 增量生成

yaml

# 只生成变更的文件
additionalProperties:
  skipOverwrite: true  # 跳过未修改的文件
  generateAliasAsModel: true

总结

正确的安装和配置是使用 OpenAPI Generator 的第一步。通过：

🎯 选择合适的安装方式
⚙️ 正确配置环境
🔧 集成到开发工具
📋 建立项目标准

您就可以开始享受 API-First 开发带来的效率提升了！

OpenAPI Generator 安装配置 ​

系统要求 ​

基础要求 ​

可选组件 ​

安装方式 ​

方式 1: npm 安装（推荐） ​

项目级安装 ​

方式 2: Docker 安装 ​

Docker Compose 配置 ​

方式 3: Homebrew 安装（macOS/Linux） ​

方式 4: 直接下载 JAR ​

配置文件 ​

全局配置 ​

项目配置 ​

环境变量配置 ​

IDE 集成 ​

VS Code 扩展 ​

IntelliJ IDEA 配置 ​

验证安装 ​

基础验证脚本 ​

生成器列表 ​

常见问题 ​

1. Java 版本问题 ​

2. 内存不足 ​

3. 代理问题 ​

4. 权限问题 ​

升级指南 ​

检查更新 ​

升级步骤 ​

性能优化 ​

1. 并行生成 ​

2. 缓存配置 ​

3. 增量生成 ​

总结 ​

OpenAPI Generator 安装配置

系统要求

基础要求

可选组件

安装方式

方式 1: npm 安装（推荐）

项目级安装

方式 2: Docker 安装

Docker Compose 配置

方式 3: Homebrew 安装（macOS/Linux）

方式 4: 直接下载 JAR

配置文件

全局配置

项目配置

环境变量配置

IDE 集成

VS Code 扩展

IntelliJ IDEA 配置

验证安装

基础验证脚本

生成器列表

常见问题

1. Java 版本问题

2. 内存不足

3. 代理问题

4. 权限问题

升级指南

检查更新

升级步骤

性能优化

1. 并行生成

2. 缓存配置

3. 增量生成

总结