Linux环境下Swagger代码生成器的使用方法
一 工具选择与准备
- 在 Linux 上，常用的代码生成工具有两类：
- Swagger Codegen（v2）：经典工具，基于 Java 运行，使用方式如 java -jar swagger-codegen-cli.jar。适合已有 v2 工作流或历史项目维护。
- OpenAPI Generator（v3/v4+）：社区更活跃，支持更多语言与框架，提供 CLI、Maven/Gradle 插件、npm 全局包 等多种使用方式。新项目优先选用。
- 环境准备：
- 安装 Java 8+（Swagger Codegen 需要 Java 环境）。
- 可选：安装 Node.js/npm（用于 OpenAPI Generator 的 npm 包或 Swagger Editor/UI 的容器化使用）。
二 安装方式
- OpenAPI Generator（推荐）
- npm 全局安装 CLI：
- 命令：npm install -g @openapitools/openapi-generator-cli
- 验证：openapi-generator-cli version
- Swagger Codegen（v2）
- 直接下载可执行 JAR（示例版本 2.4.15）：
- 命令：wget https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.15/swagger-codegen-cli-2.4.15.jar -O swagger-codegen-cli.jar
- 验证：java -jar swagger-codegen-cli.jar help
- Docker 方式（免安装，适合 Swagger Editor/UI 或生成器）
- 拉取并运行 Swagger Editor：
- 命令：docker pull swaggerapi/swagger-editor
- 运行：docker run -p 8080:8080 -d swaggerapi/swagger-editor
- 访问：http://localhost:8080
- 说明：也可通过 Docker 运行 Swagger UI 或代码生成镜像，便于在 CI/CD 中使用。
三 基本用法
- 准备规范文件：使用 OpenAPI 3.0 的 YAML/JSON（如 swagger.yaml），示例片段：
- openapi: 3.0.0
- info: { title: Sample API, version: 1.0.0 }
- paths: { “/users”: { get: { summary: List all users, responses: { ‘200’: { description: An array of users } } } } }
- 生成客户端代码（以 Java 为例）
- OpenAPI Generator：
- 命令：openapi-generator-cli generate -i swagger.yaml -g java -o ./generated/java-client
- Swagger Codegen（v2）：
- 命令：java -jar swagger-codegen-cli.jar generate -i swagger.yaml -l java -o ./generated/java-client
- 常用参数
- -i：输入规范路径（本地文件或 URL，如 http://petstore.swagger.io/v2/swagger.json）
- -g / -l：指定生成器/语言（如 java、python、typescript-angular、nodejs-server）
- -o：输出目录
- -c：自定义配置文件（JSON）
- –api-package / --model-package / --invoker-package：自定义包名
- -s：不覆盖已存在文件
- 查看语言专属可配置项：openapi-generator-cli config-help -g java 或 java -jar swagger-codegen-cli.jar config-help -l java
- 生成服务器存根或文档
- 服务器示例：openapi-generator-cli generate -i swagger.yaml -g nodejs-server -o ./generated/node-server
- 文档示例：java -jar swagger-codegen-cli.jar generate -i swagger.yaml -l html2 -o ./generated/docs。
四 集成到构建与CI
- Maven 插件（OpenAPI Generator）
- 插件配置示例：
- groupId：org.openapitools
- artifactId：openapi-generator-maven-plugin
- version：5.2.1
- 关键参数：inputSpec、generatorName、outputDir
- 典型用法：在构建阶段自动生成源码到 target/generated-sources，随后参与编译与打包。
- Gradle 插件（OpenAPI Generator）
- 插件与任务示例：
- 插件：id ‘org.openapitools.codegen’ version ‘5.2.1’
- 任务配置：inputSpec、generatorName、outputDir
- 典型用法：在 build.gradle 中定义任务，执行 gradle openApiGenerate 生成代码，再纳入编译流程。
五 常见问题与实用建议
- 规范版本与工具匹配
- 使用 OpenAPI 3.x 规范时优先选择 OpenAPI Generator；若必须使用 Swagger Codegen，请确认所用版本对 3.x 的支持情况（多数场景下更推荐前者）。
- 远程规范与认证
- 通过 -i 直接拉取远程 swagger.json 时，如接口需要鉴权，可使用 -a 传入 Authorization 等请求头信息（URL-encoded 的 name,value 对，多个值用逗号分隔）。
- 包名与代码风格
- 通过 –api-package / --model-package / --invoker-package 统一包结构，便于与现有项目规范对齐。
- 避免覆盖与模板定制
- 使用 -s 防止覆盖已有文件；如需深度定制，可通过 -t 指定自定义模板目录（高级用法）。
- 容器化与一致性
- 在 CI/CD 中优先使用 Docker 运行生成器或 Editor/UI，可显著降低环境差异带来的构建不确定性。