开发工具代码生成API设计【免费下载链接】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点击查看免费下载本篇技术指南以 swagger-codegen 仓库中的 swagger-codegen-maven-plugin 官方 README 为主体系统讲解如何把 swagger-codegen 的模板驱动代码生成引擎接入 Maven 构建生命周期实现解析 OpenAPI / Swagger 定义 → 自动生成 API 客户端、服务端桩代码与文档的自动化流水线。读完本文你将掌握插件的最小接入方式、全部通用配置参数、自定义生成器Custom Generator的扩展方法以及从源码层面理解插件内部如何调用CodegenConfigurator与DefaultGenerator完成代码生成并能直接复用仓库中提供的 示例工程 落地到自己的项目。插件定位让代码生成成为构建的一环swagger-codegen 本身是一个模板驱动的代码生成引擎通过解析 OpenAPI / Swagger 定义可以为数十种语言生成 API 客户端、服务端桩代码和文档各语言生成器的完整清单可参考 docs/generators.md。命令行方式java -jar swagger-codegen-cli.jar适合一次性生成而 swagger-codegen-maven-plugin 则把同样的能力封装为一个标准的 Maven Mojo使代码生成自动绑定到构建生命周期中无需单独记忆 CLI 参数所有配置都在pom.xml中以声明式 XML 呈现可随项目一起版本化生成动作默认绑定到generate-sources阶段与mvn compile、mvn package无缝衔接支持把生成目录自动注册为编译源码根addCompileSourceRoot生成的 Java 类型可以直接被编译并打入项目产物。从仓库源码看插件的主体只有一个 Mojo 类 CodeGenMojo.java它以Mojo(name generate, defaultPhase LifecyclePhase.GENERATE_SOURCES, threadSafe true)声明了名为generate的 goalCodeGenMojo.java 第 53 行。这个 goal 的作用在类注释中写得很明确Generates client/server code from a swagger json/yaml definition.即从 Swagger 的 JSON/YAML 定义生成客户端或服务端代码。快速开始最小配置接入在pom.xml的build → plugins节点中加入以下配置即可接入插件默认绑定generate-sources阶段。这是 README 中给出的标准最小配置plugin groupIdio.swagger/groupId artifactIdswagger-codegen-maven-plugin/artifactId version2.3.1/version executions execution goals goalgenerate/goal /goals configuration inputSpec${project.basedir}/src/main/resources/api.yaml/inputSpec languagejava/language configOptions sourceFoldersrc/gen/java/main/sourceFolder /configOptions /configuration /execution /executions /plugin配置完成后执行构建即可触发代码生成mvn clean compile这里有两个必填参数inputSpecOpenAPI/Swagger 规格文件路径支持本地文件路径language目标生成语言例如java、spring、python、go等对应 modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/ 目录下各语言生成器类。configOptions中的sourceFolder则指定了生成代码在输出目录下的子文件夹示例中为src/gen/java/main。从源码看这个值会被插件在addCompileSourceRootIfConfigured()方法中读取用于把output / sourceFolder注册为编译源码根CodeGenMojo.java 第 567-577 行若未指定默认按src/main/java处理。版本提示README 与示例工程中的插件版本为2.3.1而当前仓库modules/swagger-codegen-maven-plugin/pom.xml中项目自身的版本为2.4.53-SNAPSHOT。实际使用时请以你本地 Maven 仓库中可用的发布版本为准。通用配置参数详解除inputSpec、language外插件还暴露了大量通用参数。以下参数表完整继承自 README并结合 CodeGenMojo.java 的字段声明补充了默认值与使用说明参数说明默认值 / 备注inputSpecOpenAPI/Swagger 规格文件路径必填language目标生成语言必填output生成代码的目标输出路径${project.build.directory}/generated-sources/swaggertemplateDirectory存放 mustache 模板的目录可选默认使用内置模板addCompileSourceRoot是否将输出目录注册为项目源码根使生成代码参与编译truemodelPackage生成的模型对象/类的包名可选apiPackage生成的 API 对象/类的包名可选invokerPackage生成的 invoker 对象的包名可选modelNamePrefix/modelNameSuffix为模型类与枚举统一添加前缀 / 后缀默认空字符串见 CodegenConstants.java 中MODEL_NAME_PREFIX_DESClocalVariablePrefix为所有生成的局部变量添加前缀适用于 API 方法名与局部变量名冲突的场景可选withXml在生成的模型与 API 中启用 XML 注解false仅对 Javalanguage且所选库支持 JSON 与 XML 时有效configOptions语言特定参数的映射表见下文语言特定参数可选configHelp输出指定库的配置帮助信息不生成任何源码falseignoreFileOverride指定.swagger-codegen-ignore文件的完整路径用于基于模式覆盖生成输出可选generateApis是否生成 APItruegenerateApiTests是否生成 API 测试true仅当generateApis为true时有效generateApiDocumentation是否生成 API 文档true仅当generateApis为true时有效generateModels是否生成模型truemodelsToGenerate逗号分隔的、需要生成的模型列表默认为全部模型generateModelTests是否生成模型测试true仅当generateModels为true时有效generateModelDocumentation是否生成模型文档true仅当generateModels为true时有效generateSupportingFiles是否生成支撑文件如pom.xml、README.md、git_push.sh等truesupportingFilesToGenerate逗号分隔的、需要生成的支撑文件列表默认为全部文件skip跳过代码生成false也可通过全局属性codegen.skip设置几个值得注意的源码细节skip与codegen.skip属性该参数在 CodeGenMojo.java 第 295 行 声明为Parameter(name skip, property codegen.skip, required false, defaultValue false)。这意味着除了在pom.xml中配置skiptrue/skip你也可以在命令行用-Dcodegen.skiptrue跳过生成。值得注意的是跳过生成时插件仍会调用addCompileSourceRootIfConfigured()以保证此前已生成的源码在本次构建中依然会被编译CodeGenMojo.java 第 332-338 行。生成范围由 System 属性控制generateApis、generateModels、generateSupportingFiles等开关最终会被转换为CodegenConstants中定义的 System 属性apis、models、supportingFiles、modelTests、modelDocs、apiTests、apiDocs、withXml见 CodegenConstants.java 第 9-16 行再由底层生成引擎读取CodeGenMojo.java 第 426-449 行。执行是线程安全的execute()方法通过对CodeGenMojo.class加同步锁synchronized实现朴素的线程安全策略CodeGenMojo.java 第 322-328 行配合 Mojo 声明中的threadSafe true插件可以安全地用于并行构建。环境变量在生成后会被还原插件会把environmentVariables中配置的键值写入 System 属性并在生成结束后恢复原值避免连续多次执行不同配置的生成任务时产生串味CodeGenMojo.java 第 518-530 行与第 579-588 行。语言特定参数configOptionsconfigOptions是一个键值映射用来传递各语言生成器专属的参数。不同语言支持的选项不同可以通过configHelp参数查看在插件配置中将configHelptrue/configHelp打开并运行构建插件就会遍历当前语言生成器的cliOptions()把每个选项名与帮助说明打印出来且不生成任何源码CodeGenMojo.java 第 544-552 行。在configOptions中比较常用的语言参数包括dateLibrary日期时间库如joda、sourceFolder生成源码子目录、libraryHTTP 客户端库如jersey2、okhttp-gson、feign等等。README 中关于语言特定配置的说明可结合 docs/generators-configuration.md 阅读其中也介绍了通过-c config.json配置文件传递这些选项的等价做法。其他可在插件中配置的映射参数除了上述参数CodeGenMojo.java 还声明了一批映射类参数它们与命令行工具的--type-mappings、--import-mappings等选项一一对应同样支持以 XML 列表形式配置instantiationTypes类型与其实例化类型的映射importMappings类与其导入路径的映射可用于自带模型场景例如把Pet映射到自己的my.models.MyPettypeMappingsSwagger 规格类型到生成代码类型的映射languageSpecificPrimitives额外的语言特定原始类型列表additionalProperties额外的键值对属性可在 mustache 模板中引用reservedWordsMappings保留字及其转义方式的映射。这些参数的解析逻辑在 CodegenConfiguratorUtils.java 中插件同时兼容两种写法在configOptions中以旧式instantiation-types、import-mappings等键传递或以独立的 XML 列表节点直接配置CodeGenMojo.java 第 451-516 行。自定义生成器Custom Generator当内置的语言生成器无法满足需求时插件支持指定自定义生成器。README 中特别强调自定义生成器不支持classpath:语法但支持类的全限定名fully qualified name同时你也可以指定自定义模板目录自定义模板会被一并加载。承载生成器/模板的依赖以dependencies形式声明在插件作用域内。plugin groupIdio.swagger/groupId artifactIdswagger-codegen-maven-plugin/artifactId version${swagger-codegen-maven-plugin-version}/version executions execution goals goalgenerate/goal /goals configuration inputSpec${project.basedir}/src/main/resources/yaml/yamlfilename.yaml/inputSpec !-- language file, like e.g. JavaJaxRSCodegen shipped with swagger -- languagecom.my.package.for.GeneratorLanguage/language templateDirectorymyTemplateDir/templateDirectory output${project.build.directory}/generated-sources/output apiPackage${default.package}.handler/apiPackage modelPackage${default.package}.model/modelPackage invokerPackage${default.package}.handler/invokerPackage /configuration /execution /executions dependencies dependency groupIdcom.my.generator/groupId artifactIdcustomgenerator/artifactId version1.0-SNAPSHOT/version /dependency /dependencies /plugin要点解读language不再填java这样的短名而是填自定义生成器类的全限定名例如com.my.package.for.GeneratorLanguage。这与命令行方式中-l com.mycompany.swagger.codegen.MyObjcCodegen的用法一致——自定义生成器通常通过继承某个内置生成器类如ObjcClientCodegen并覆写默认值来实现参见 docs/generators-configuration.md。templateDirectory指向自定义 mustache 模板目录插件会把templateDirectory.getAbsolutePath()设置到配置器上CodeGenMojo.java 第 422-424 行。dependencies中声明自定义生成器/模板 jar依赖插件运行时即可从插件类加载器加载到该 jar 中的生成器类与模板资源。插件底层执行链路从源码层面梳理插件一次生成的完整调用链有助于理解各参数的实际作用。核心入口是 CodeGenMojo.execute()其内部流程如下跳过检查若skip为true记录日志并直接返回仍会注册编译源码根构建配置器先尝试从configurationFile读取CodegenConfigurator对应命令行-c config.json的等价能力读取失败或未配置时新建一个空的配置器CodeGenMojo.java 第 341-346 行填充配置把 Mojo 参数逐一set到CodegenConfigurator上包括inputSpec、language、outputDir、templateDir、包名、library、前缀后缀、auth、ignoreFileOverride等CodeGenMojo.java 第 348-424 行设置生成开关把generateApis等布尔开关转为 System 属性见上文生成范围由 System 属性控制应用映射与语言参数处理configOptions及instantiationTypes、importMappings、typeMappings、languageSpecificPrimitives、additionalProperties、reservedWordsMappings随后通过configurator.toClientOptInput()得到ClientOptInput并把configOptions中命中该语言cliOptions()的键写入additionalProperties()从而真正作用到模板渲染CodeGenMojo.java 第 488-542 行执行生成调用new DefaultGenerator().opts(input).generate()完成实际代码生成CodeGenMojo.java 第 553-562 行。生成失败时插件会先把异常完整打印到日志不依赖-e参数再抛出MojoExecutionException注册编译源码根若addCompileSourceRoot为true把output/sourceFolder通过project.addCompileSourceRoot(...)注册为编译源码根CodeGenMojo.java 第 567-577 行随后还原被改写的环境变量。这段链路意味着插件本身并不实现代码生成逻辑而是 swagger-codegen 引擎io.swagger.codegen包下的CodegenConfiguratorDefaultGenerator在 Maven 世界中的适配层——插件负责把 XML 配置翻译成引擎可识别的配置对象与属性引擎负责解析规格、加载模板并落盘生成文件。示例工程一个完整的 Java 客户端生成配置仓库的 examples 目录 提供了开箱即用的示例java-client.xml是一个完整的可参考 POMswagger.yaml是配套的 Petstore Swagger 2.0 规格包含pet、store、user三组操作、oauth2 与 apiKey 两种安全定义以及Pet、Order、User等模型定义。examples/java-client.xml 的关键配置如下plugin groupIdio.swagger/groupId artifactIdswagger-codegen-maven-plugin/artifactId version2.3.1/version executions execution goals goalgenerate/goal /goals configuration !-- specify the swagger yaml -- inputSpecswagger.yaml/inputSpec !-- target to generate java client code -- languagejava/language !-- hint: if you want to generate java server code, e.g. based on Spring Boot, you can use the following target: languagespring/language -- !-- pass any necessary config options -- configOptions dateLibraryjoda/dateLibrary /configOptions !-- override the default library to jersey2 -- libraryjersey2/library /configuration /execution /executions /plugin示例的编排体现了三类典型配置的配合生成目标languagejava/language生成 Java 客户端如需生成 Spring Boot 服务端可按注释提示切换为languagespring/language对应samples/server/petstore/springboot/目录下的生成产物形态语言特定参数configOptionsdateLibraryjoda/dateLibrary/configOptions让生成的模型使用 Joda-Time 处理日期时间库覆盖libraryjersey2/library把默认 HTTP 客户端库Java 默认通常为okhttp-gson替换为 Jersey 2。与此同时示例 POM 还演示了生成代码的运行时依赖配套在使用jersey2库时需要在项目dependencies中补充swagger-annotations、jersey-client、jersey-media-json-jackson、jackson-*系列、jackson-datatype-joda、joda-time以及migbase64Base64 编解码兼容 JVM 与 Android等依赖版本通过properties统一管理示例中jersey-version为 2.29.1、jackson-version为 2.11.4、jodatime-version为 2.7。这与仓库中 samples/client/petstore/java/jersey2 生成的完整 Java 客户端工程的依赖结构一致可以作为落地时的对照参考。常见进阶用法与建议生成范围裁剪大型规格一次生成全部内容可能过重。可用modelsToGenerate、supportingFilesToGenerate精确控制生成子集或用generateApisfalse、generateModelsfalse、generateSupportingFilesfalse关闭某一类产物文档generateApiDocumentation/generateModelDocumentation与测试generateApiTests/generateModelTests也都可以独立开关。忽略文件.swagger-codegen-ignoreignoreFileOverride指向一个.swagger-codegen-ignore文件实现对生成输出的模式化覆盖比简单的是否覆盖更精细。该文件必须位于输出目录根下ignoreFileOverride是完整覆盖complete override在重新生成时优先于输出目录中的.swagger-codegen-ignore生效详见 docs/generators.md 中的说明。CI 中跳过生成在已经生成并提交代码、或希望临时加速构建时通过-Dcodegen.skiptrue或配置skiptrue/skip即可跳过生成且不影响已生成源码的编译。排查参数遇到某语言有哪些可用参数的问题时打开configHelp运行一次即可获得该语言生成器完整的 CLI 选项与帮助文本这是不写代码就能确认语言特定参数名与默认值的快捷途径。总而言之swagger-codegen-maven-plugin 将 OpenAPI/Swagger 规格驱动的代码生成无缝嵌入 Maven 构建流程一个generategoal、一份 XML 配置即可在每次构建时自动产出跨语言的 API 客户端、服务端桩代码与文档而自定义生成器与模板目录机制则让团队可以在不修改 swagger-codegen 本体的情况下定制专属代码风格。赞分享开发工具代码生成API设计【免费下载链接】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点击查看免费下载相关推荐swagger-codegen 在线生成器实战通过 HTTP API 一键生成多语言 API 客户端与服务端代码swagger codegen 在线生成器实战通过 HTTP API 一键生成多语言 API 客户端与服务端代码 本指南聚焦 swagger codegen开发工具代码生成API设计Swagger to JS TypeScript Codegen高效生成API客户端代码的利器Swagger to JS TypeScript Codegen高效生成API客户端代码的利器 在现代软件开发中API文档的规范化和自动化生成代码是提高开发工具如何用文献分析与总结工具告别通宵读文献如何用文献分析与总结工具告别通宵读文献 凌晨一点你的桌面上摊着 200 篇 PDF开题报告的 deadline 还剩三天。你已经翻完了前六篇唯一记住的是开发工具代码生成API设计上一篇3种方法深度解析PC端微信Hook机器人逆向开发实战下一篇10个GoView实用技巧让你的数据可视化大屏交互体验瞬间升级创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考