Linux环境下Swagger代码生成器的使用方法

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，可显著降低环境差异带来的构建不确定性。

最新问答