Swagger Codegen Maven 插件实战指南一份配置把 OpenAPI 规范变成多语言客户端【免费下载链接】swagger-codegenswagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.项目地址: https://gitcode.com/gh_mirrors/sw/swagger-codegen写 REST 接口后模型类、API 调用代码、接口文档这些重复劳动总让人头疼。swagger-codegen 是一个模板驱动的代码生成引擎解析你的 OpenAPI / Swagger 定义就能生成文档、API 客户端和服务器存根。而swagger-codegen-maven-plugin让这件事直接挂进 Maven 构建每次mvn compile代码自动长出来。这篇文章不讲参数清单而是按任务走先让生成跑通再依次解决改代码风格改生成逻辑一次出多语言三个常见诉求最后给避坑技巧和速查表。快速上手五分钟让插件生成代码在pom.xml的build plugins里加一段插件声明。它绑定的 goal 是generate默认在generate-sources阶段执行plugin groupIdio.swagger/groupId artifactIdswagger-codegen-maven-plugin/artifactId version2.3.1/version executions execution goalsgoalgenerate/goal/goals configuration inputSpec${project.basedir}/src/main/resources/api.yaml/inputSpec languagejava/language /configuration /execution /executions /plugin只有三个必填项inputSpecOpenAPI 规范文件路径、language目标语言如java、spring、typescript-angular。然后运行mvn clean compile✅ 生成的代码默认落在target/generated-sources/swagger插件还会把它加进编译源目录addCompileSourceRoot默认true所以生成出来的 Java 类直接参与编译不需要额外配置。想换生成代码的风格指向自定义模板目录插件底层用 Mustache 模板引擎一种用{{变量}}占位的模板格式渲染每个文件。模板里找不到对应片段就从默认模板兜底。默认模板长什么样内置模板都放在 modules/swagger-codegen/src/main/resources/ 下按语言分目录。比如 Java 客户端模板在Java/子目录里核心文件就三个api.mustache—— 每个 API 对应的调用类model.mustache—— 每个模型对应的 POJOApiClient.mustache—— HTTP 客户端基类只替换你要改的那几个模板把默认模板拷到项目里比如src/main/resources/templates/Java只改需要动的部分再告诉插件模板目录configuration inputSpec.../api.yaml/inputSpec languagejava/language templateDirectory${project.basedir}/src/main/resources/templates/templateDirectory /configuration模板里可以用规范中的变量写条件逻辑例如给废弃模型自动加deprecated/** * {{description}} * {{#isDeprecated}}deprecated{{/isDeprecated}} */ public class {{classname}} { ... } 模板目录里没写的文件不会覆盖默认行为所以增量式改模板是安全的——你不需要一次性拷贝整个默认目录。想改生成逻辑本身注入一个自定义生成器改模板解决的是长什么样如果你要动怎么生成——比如往 pom 里追加依赖、改类型映射、注册额外支持文件——就要写自定义生成器。思路很简单继承对应语言的生成器类重写方法。上面这张图展示的是项目内 java-pkmst 生成器的结构自定义生成器类复用核心 Mustache 模板目录再叠加自己的扩展功能。写一个最小生成器package com.example.codegen; import io.swagger.codegen.languages.JavaClientCodegen; public class MyJavaCodegen extends JavaClientCodegen { Override public void processOpts() { super.processOpts(); // 往模板里注入自定义属性可在 mustache 中引用 additionalProperties.put(customHeader, generated by my-team); } }把它连同模板打成一个 jar 发布然后插件配置里用全限定类名替换language并在插件的dependencies里引入这个 jarconfiguration languagecom.example.codegen.MyJavaCodegen/language templateDirectorymyTemplateDir/templateDirectory /configuration dependencies dependency groupIdcom.example/groupId artifactIdcustom-generator/artifactId version1.0.0/version /dependency /dependencies⚠️ 注意language写自定义生成器时不支持classpath:/语法必须写包名加类名的全限定名依赖要挂在插件的dependencies里即 plugin scope而不是项目依赖。想一次生成多语言声明多个 execution同一个规范文件给 Java 后端和 TypeScript 前端各出一份客户端再复制一个execution节点即可每个节点带独立id配置互不干扰execution idgen-java/id goalsgoalgenerate/goal/goals configuration inputSpec.../api.yaml/inputSpec languagejava/language output${project.build.directory}/gen/java/output /configuration /execution execution idgen-ts/id goalsgoalgenerate/goal/goals configuration inputSpec.../api.yaml/inputSpec languagetypescript-angular/language output${project.build.directory}/gen/ts/output /configuration /execution多语言并存时记得用output把各自的输出目录隔开否则后执行的会覆盖先执行的结果。增量生成与避坑别让你手改的代码被冲掉规范一变就重新生成最怕把上次手补的逻辑洗掉。插件给了几层保护。用 ignore 文件圈出不可动的文件.swagger-codegen-ignore语法和.gitignore一样放在输出目录根部生效# 不重新生成任何测试文件 **/*Test.java # 保留手工改过的 ApiClient !src/main/java/io/swagger/client/ApiClient.java想让规则文件放在输出目录之外统一维护可以用ignoreFileOverride指定它的完整路径。规则写法/锚定根、**递归、!反选详见 docs/generators.md 的 Ignore file format 一节。常用开关按需裁剪生成范围目的配置只生成部分模型modelsToGeneratePet,Store/modelsToGenerate逗号分隔跳过某类产物generateApiTestsfalse/generateApiTests等不覆盖已存在的文件skipOverwritetrue/skipOverwrite整个构建跳过生成命令行加-Dcodegen.skiptrue只查某语言支持哪些参数configHelptrue/configHelp打印帮助、不生成代码modelsToGenerate比 ignore 文件更彻底它直接告诉生成器只处理这几个模型适合规范里有一大堆你根本不用的模型的场景。关键配置速查配置项作用默认值inputSpecOpenAPI 规范路径必填-language目标语言或自定义生成器全限定类名必填-output输出目录target/generated-sources/swaggertemplateDirectory自定义 Mustache 模板目录内置模板configOptions语言特定参数如sourceFolder、dateLibrary-apiPackage/modelPackage/invokerPackage生成类的包名语言默认包library同一语言下的 HTTP 库变体如jersey2语言默认库ignoreFileOverride自定义 ignore 文件路径输出目录根部withXml模型和 API 里加 XML 注解Java 专用falseaddCompileSourceRoot输出目录加入编译源根trueskip跳过生成可用-Dcodegen.skip全局控制false延伸阅读插件全部参数与自定义生成器示例modules/swagger-codegen-maven-plugin/README.md可直接参考的完整 pom 示例modules/swagger-codegen-maven-plugin/examples/java-client.xml各语言生成器与 ignore 文件规则docs/generators.md生成器通用配置说明docs/generators-configuration.md插件入口实现Mojo 参数如何映射到配置器modules/swagger-codegen-maven-plugin/src/main/java/io/swagger/codegen/plugin/CodeGenMojo.java各语言默认 Mustache 模板源码modules/swagger-codegen/src/main/resources/【免费下载链接】swagger-codegenswagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.项目地址: https://gitcode.com/gh_mirrors/sw/swagger-codegen创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考