OpenAPI Generator 如何用 author template 提取内置模板进行本地修改【免费下载链接】openapi-generatorOpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)项目地址: https://gitcode.com/GitHub_Trending/op/openapi-generator当你用 OpenAPI Generator 生成的客户端或 Server Stub 需要融入自己的内部逻辑日志、监控、故障处理等时最省事的方式是修改 Mustache 模板而不是改生成代码。从 OpenAPI Generator 5.0 开始CLI 提供了author template命令可以把目标生成器的内置模板直接从 CLI jar 中提取到本地目录供你逐个修改。适用于已安装 openapi-generator-cli 5.0 及以上版本的任意平台环境本文以提取并修改 Java 生成器模板为例说明完整的操作路径。前提条件安装 openapi-generator-cli。跨平台方式是通过 npm 全局安装安装文档见 docs/installation.mdnpm install openapitools/openapi-generator-cli -gnpm 包是对 JAR 的命令行封装会跨操作系统统一参数传递方式。macOS 也可以用brew install openapi-generatorWindows 可以用scoop install openapi-generator-cli另外还有 pip、Docker、直接下载 JAR 等方式任选其一即可。安装完成后可用openapi-generator-cli version确认版本在 5.0 及以上。author命令组定位为 Utilities for authoring generators or customizing templates其中的template子命令的作用是 Retrieve templates for local modification即把模板从 CLI jar 中取出来以便本地修改。提取模板的命令与参数author template的参数如下取自 docs/usage.md 中的帮助输出openapi-generator-cli author template (-g generator name | --generator-name generator name) [--library library] [(-o output directory | --output output directory)] [(-v | --verbose)]-g/--generator-name必填要提取模板的生成器名称可用list命令查看全部可用生成器--library可选。带上该选项后libraries目录下只保留对应 library 的模板文件其余 library 子目录被过滤-o/--output模板写出目录不指定时默认为out-v/--verbose输出每个模板文件的复制细节。提取全部 Java 模板openapi-generator-cli author template -g java只提取 Java 生成器中webclientlibrary 的模板文档给出的示例openapi-generator-cli author template -g java --library webclient加-o可以指定输出位置例如写到~/.openapi-generator/templates/Java。验证提取结果命令成功时会输出一行信息Extracted templates to out directory. Refer to .../docs/templating for customization details.进入输出目录检查文件结构即可确认ls out你应该看到该生成器的.mustache模板文件以及libraries/目录支持library选项的生成器才有。如果加了--library webclientlibraries/下应只剩webclient子目录。提取失败时常见的报错是 library 名称拼写错误此时会看到类似The library xxx was not extracted. Please verify the spelling and retry.的警告对照生成器支持的 library 列表修正后重试。加-v可以看到每个文件从 jar 内拷贝到本地的过程便于定位问题。修改模板前的必要理解只能覆盖不能新建。文档明确说明user-defined templates 只能覆盖已有模板不能借此创建全新的模板集。要贡献新生成器用仓库根目录的new.sh要创建带更强模板控制能力的私有生成器见 customization。只需要提取并修改你要改的那一个文件。生成器查找模板的顺序是用户自定义 library 路径如custom_template/libraries/feign/model.mustache用户自定义生成器顶层路径如custom_template/model.mustache内置 library 路径如resources/Java/libraries/feign/model.mustache内置顶层路径如resources/Java/model.mustache公共内置路径如resources/_common/model.mustache所以只改生成 README 这类单一逻辑时只提取并修改对应的那一个 mustache 文件即可其余文件走内置回退。可选先建 git 仓库便于回退。文档建议在修改前执行git init git add . git commit -am initial这样能随时回到未修改的基准模板。用修改后的模板生成代码修改完成后执行generate通过-t指向模板目录。注意一个容易踩的坑-t必须传生成器的根目录不能只传 library 子目录——生成时未覆盖的部分会回退到根模板。本仓库中自带测试用的 petstore 规格文件可直接作为输入modules/openapi-generator/src/test/resources/3_0/petstore.yaml。生成一条完整的命令示例模板目录换成你的输出目录openapi-generator-cli generate -g java --library resteasy \ -t ~/.openapi-generator/templates/Java \ -o ~/.openapi-generator/example \ -i modules/openapi-generator/src/test/resources/3_0/petstore.yaml进入输出目录构建确认生成的代码可以编译cd ~/.openapi-generator/example gradle assembledocs/templating.md 给出了一个完整的修改范例给 Java 客户端模板加入 jcabi-aspects 的LoggableAOP 日志包括在build.gradle.mustache中添加依赖、在api.mustache中加 import 和注解最后运行./gradlew build并检查target/rolling/rollingtest.log验证每次PetApi调用都产生了日志。可以参考该文档的 diff 了解最小修改面——libraries/resteasy/下只有 6 个文件ApiClient.mustache、JSON.mustache、api.mustache、build.gradle.mustache、build.sbt.mustache、pom.mustache扩展一个 library 通常只需要改其中几个。修改模板时如果不确定某个变量是否存在可以加--global-property debugOpenAPItrue生成输出完整传给模板的对象模型来对照。限制与替代路径版本限制author template仅在 5.0 及以上可用。旧版本的替代做法是去源码仓库找生成器的 resources 目录约定为resources/generator name或查看生成器类构造函数中的embeddedTemplateDir赋值。例如 C# 生成器是embeddedTemplateDir templateDir csharp;对应源码中的 modules/openapi-generator/src/main/resources/csharp。取模板时务必选择与你当前使用的 OpenAPI Generator 版本一致的 tag 或分支。library 选项的已知列表支持library选项的生成器只认编译期已知的 library 名称传入自定义 library 名会在运行时报错。冗余文件敏感部分生成器对哪些文件存在敏感。如果担心pom.mustache、build.sbt.mustache这类冗余文件可以先删除试试若运行时失败用touch创建一个空文件即可恢复。classpath 模板如果要在多个项目间复用模板也可以把模板打进 jar 放到 classpath 中通过java -cp ... org.openapitools.codegen.OpenAPIGenerator方式调用详见 docs/templating.md 的 classpath 示例。【免费下载链接】openapi-generatorOpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)项目地址: https://gitcode.com/GitHub_Trending/op/openapi-generator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenAPI Generator 如何用 author template 提取内置模板进行本地修改？
OpenAPI Generator 如何用 author template 提取内置模板进行本地修改【免费下载链接】openapi-generatorOpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)项目地址: https://gitcode.com/GitHub_Trending/op/openapi-generator当你用 OpenAPI Generator 生成的客户端或 Server Stub 需要融入自己的内部逻辑日志、监控、故障处理等时最省事的方式是修改 Mustache 模板而不是改生成代码。从 OpenAPI Generator 5.0 开始CLI 提供了author template命令可以把目标生成器的内置模板直接从 CLI jar 中提取到本地目录供你逐个修改。适用于已安装 openapi-generator-cli 5.0 及以上版本的任意平台环境本文以提取并修改 Java 生成器模板为例说明完整的操作路径。前提条件安装 openapi-generator-cli。跨平台方式是通过 npm 全局安装安装文档见 docs/installation.mdnpm install openapitools/openapi-generator-cli -gnpm 包是对 JAR 的命令行封装会跨操作系统统一参数传递方式。macOS 也可以用brew install openapi-generatorWindows 可以用scoop install openapi-generator-cli另外还有 pip、Docker、直接下载 JAR 等方式任选其一即可。安装完成后可用openapi-generator-cli version确认版本在 5.0 及以上。author命令组定位为 Utilities for authoring generators or customizing templates其中的template子命令的作用是 Retrieve templates for local modification即把模板从 CLI jar 中取出来以便本地修改。提取模板的命令与参数author template的参数如下取自 docs/usage.md 中的帮助输出openapi-generator-cli author template (-g generator name | --generator-name generator name) [--library library] [(-o output directory | --output output directory)] [(-v | --verbose)]-g/--generator-name必填要提取模板的生成器名称可用list命令查看全部可用生成器--library可选。带上该选项后libraries目录下只保留对应 library 的模板文件其余 library 子目录被过滤-o/--output模板写出目录不指定时默认为out-v/--verbose输出每个模板文件的复制细节。提取全部 Java 模板openapi-generator-cli author template -g java只提取 Java 生成器中webclientlibrary 的模板文档给出的示例openapi-generator-cli author template -g java --library webclient加-o可以指定输出位置例如写到~/.openapi-generator/templates/Java。验证提取结果命令成功时会输出一行信息Extracted templates to out directory. Refer to .../docs/templating for customization details.进入输出目录检查文件结构即可确认ls out你应该看到该生成器的.mustache模板文件以及libraries/目录支持library选项的生成器才有。如果加了--library webclientlibraries/下应只剩webclient子目录。提取失败时常见的报错是 library 名称拼写错误此时会看到类似The library xxx was not extracted. Please verify the spelling and retry.的警告对照生成器支持的 library 列表修正后重试。加-v可以看到每个文件从 jar 内拷贝到本地的过程便于定位问题。修改模板前的必要理解只能覆盖不能新建。文档明确说明user-defined templates 只能覆盖已有模板不能借此创建全新的模板集。要贡献新生成器用仓库根目录的new.sh要创建带更强模板控制能力的私有生成器见 customization。只需要提取并修改你要改的那一个文件。生成器查找模板的顺序是用户自定义 library 路径如custom_template/libraries/feign/model.mustache用户自定义生成器顶层路径如custom_template/model.mustache内置 library 路径如resources/Java/libraries/feign/model.mustache内置顶层路径如resources/Java/model.mustache公共内置路径如resources/_common/model.mustache所以只改生成 README 这类单一逻辑时只提取并修改对应的那一个 mustache 文件即可其余文件走内置回退。可选先建 git 仓库便于回退。文档建议在修改前执行git init git add . git commit -am initial这样能随时回到未修改的基准模板。用修改后的模板生成代码修改完成后执行generate通过-t指向模板目录。注意一个容易踩的坑-t必须传生成器的根目录不能只传 library 子目录——生成时未覆盖的部分会回退到根模板。本仓库中自带测试用的 petstore 规格文件可直接作为输入modules/openapi-generator/src/test/resources/3_0/petstore.yaml。生成一条完整的命令示例模板目录换成你的输出目录openapi-generator-cli generate -g java --library resteasy \ -t ~/.openapi-generator/templates/Java \ -o ~/.openapi-generator/example \ -i modules/openapi-generator/src/test/resources/3_0/petstore.yaml进入输出目录构建确认生成的代码可以编译cd ~/.openapi-generator/example gradle assembledocs/templating.md 给出了一个完整的修改范例给 Java 客户端模板加入 jcabi-aspects 的LoggableAOP 日志包括在build.gradle.mustache中添加依赖、在api.mustache中加 import 和注解最后运行./gradlew build并检查target/rolling/rollingtest.log验证每次PetApi调用都产生了日志。可以参考该文档的 diff 了解最小修改面——libraries/resteasy/下只有 6 个文件ApiClient.mustache、JSON.mustache、api.mustache、build.gradle.mustache、build.sbt.mustache、pom.mustache扩展一个 library 通常只需要改其中几个。修改模板时如果不确定某个变量是否存在可以加--global-property debugOpenAPItrue生成输出完整传给模板的对象模型来对照。限制与替代路径版本限制author template仅在 5.0 及以上可用。旧版本的替代做法是去源码仓库找生成器的 resources 目录约定为resources/generator name或查看生成器类构造函数中的embeddedTemplateDir赋值。例如 C# 生成器是embeddedTemplateDir templateDir csharp;对应源码中的 modules/openapi-generator/src/main/resources/csharp。取模板时务必选择与你当前使用的 OpenAPI Generator 版本一致的 tag 或分支。library 选项的已知列表支持library选项的生成器只认编译期已知的 library 名称传入自定义 library 名会在运行时报错。冗余文件敏感部分生成器对哪些文件存在敏感。如果担心pom.mustache、build.sbt.mustache这类冗余文件可以先删除试试若运行时失败用touch创建一个空文件即可恢复。classpath 模板如果要在多个项目间复用模板也可以把模板打进 jar 放到 classpath 中通过java -cp ... org.openapitools.codegen.OpenAPIGenerator方式调用详见 docs/templating.md 的 classpath 示例。【免费下载链接】openapi-generatorOpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)项目地址: https://gitcode.com/GitHub_Trending/op/openapi-generator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考