OpenAPITools/openapi-generator

项目介绍

OpenAPI Generator 读取 OpenAPI/Swagger 规范（支持 1.x 到 3.0，3.1 为 beta），自动生成客户端 SDK、服务端桩代码、文档和配置。它是 Swagger Codegen 的社区分支，由 40 多位原贡献者发起，面向需要跨语言统一客户端交付的 API 提供方，以及不想手写 HTTP 胶水代码的 API 使用方。项目提供 Java CLI、Maven/Gradle 插件、Docker 镜像、Node 包装器和 pip 包，也支持自托管在线生成服务。

快速使用

用 CLI JAR 时，唯一硬性前提是 Java 运行环境，文档要求至少 Java 11，可先用 java -version 确认。

下载已发布的 CLI JAR，并以 Petstore 示例生成一个客户端：

wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.27.0/openapi-generator-cli-7.27.0.jar -O openapi-generator-cli.jar
java -jar openapi-generator-cli.jar generate \
  -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml \
  -g php \
  -o /tmp/php_api_client

生成的 PHP 客户端位于 /tmp/php_api_client。把 -g php 换成其他生成器名、调整输出目录即可生成别的语言。java -jar openapi-generator-cli.jar help generate 查看通用选项，config-help -g php 查看该生成器的专属选项。

替代方式：用 Homebrew 安装（brew install openapi-generator），或用官方 CLI 镜像免去本地 JVM：

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml \
  -g go \
  -o /local/out/go

生成结果写入宿主机的 ./out/go。项目还提供在线镜像，可自托管 HTTP 生成接口用于 CI 流程。

使用约束

• CLI 依赖 JVM；pip 和 Node 包装器仍需要 Java 可执行文件，除非使用 jdk4py（要求 Python 3.10+）。当前版本一般要求 Java 11 或更新。
• 从源码构建需要 Java 11，可选 Maven 3.8.8+；项目自带 Maven wrapper，Linux/macOS 用 ./mvnw clean install，Windows 用 mvnw.cmd clean install。
• 各语言的生成器行为、选项和模板结构不同，选项按生成器分别记录，使用前应查阅对应语言的生成器文档和 config-help 输出。
• minor 版本可能包含破坏性变更（带回退机制）；实际使用时建议固定版本（launcher 脚本可设 OPENAPI_GENERATOR_VERSION，包装器指定明确版本），避免升级导致生成结果漂移。
• 生成代码刻意不受父项目 Apache-2.0 许可证约束，按原样提供，许可方式由使用者决定。
• 公开在线服务 api.openapi-generator.tech 和 api-latest-master.openapi-generator.tech 均为 beta，不保证服务级别。
• launcher 脚本会在调用时查询并下载最新版本；把它加入 PATH 前应先检查脚本内容，其自身文档也提醒要审阅从外部获取的脚本。

集成与定制

Maven、Gradle、sbt、Bazel、GitHub 与 CI/CD 的接入方式见 docs/integration.md，输出定制（包名、版本、模板等）见 docs/customization.md。社区提供了 Eclipse、IntelliJ IDEA、Visual Studio 和 VS Code 插件。内置模板仅完整支持 Mustache，其他模板引擎为实验性。

HotRepo 点评

这个项目覆盖的语言矩阵非常广，但接受度并不一致。README 自述 NPM CLI 包装器每周约 60 万次下载、CLI Docker 镜像约 3000 万次下载，说明使用面确实很大。2022 年 Hacker News 讨论中，一位评论者被多语言和 OpenAPI 3 支持吸引，却对 Java 编写生成器的强制要求、模板扩展困难以及部分生成代码的项目结构表示失望（评论）；另一位评论者表示 Go 结构体生成器难以跑通，转而使用 Deepmap 的 oapi-codegen（评论）。同一讨论中，维护者感谢了这条推荐（回复），也有竞品 SDK 厂商承认现有 OpenAPI 生成器存在 bug、生成物偏机器可读而非好用（评论）。实际取舍是：广覆盖是优势，但需要按语言逐一评估生成质量，必要时固定版本并定制模板。