OpenAPI Generator Maven 插件配置详解（SpringBoot集成）

0-1开始Java语言编程之路
一、Ubuntu下Java语言环境搭建 | MacOS下使用Jenv管理多JDK版本
二、Ubuntu下Docker环境安装 | MacOS下Docker安装与配置
三、使用Docker搭建本地Nexus Maven私有仓库
四、Ubuntu下使用VisualStudioCode进行Java开发
五、从Swagger到OpenAPI，SpringBoot集成StepByStep
六、OpenAPI Generator Maven 插件配置详解（SpringBoot集成）

上一篇文章介绍了OpenAPI Generator Maven插件的基本使用，大体来讲分三步：

• 定义API Spec，也就是xxx-service-api-spec.yaml
• 通过OpenAPI Generator Maven插件来生成SpringbootApplication框架代码
• 在框架代码基础上实现具体的业务逻辑

但还是有一些需要注意的点，比如Maven插件的配置，今天就带大家一起来看一下Maven插件都有哪些参数，又如何配置，以及又有哪些常用的配置项。

参数说明

参数名	说明	示例
verbose	是否启用详细模式，默认值为 false	true
inputSpec	指定 OpenAPI 规范文件的路径	src/main/resources/openapi.yaml
inputSpecRootDirectory	指定本地包含规范文件的根目录	src/main/resources
mergedFileName	指定合并后规范文件的名称	merged-api.yaml
language	目标生成语言（已废弃，使用 generatorName 代替）	java
generatorName	目标代码生成器名称	spring
cleanupOutput	是否在生成前清理输出目录，默认值为 false	true
output	目标输出路径，默认 ${project.build.directory}/generated-sources/openapi	generated-code
gitHost	Git 仓库主机，例如 gitlab.com	github.com
gitUserId	Git 用户 ID	my-user
gitRepoId	Git 仓库 ID	my-repo
collapsedSpec	指定 OpenAPI 规范的单文件表示路径	openapi-collapsed.yaml
includeCollapsedSpecInArtifacts	是否在 Maven 构件中包含合并规范文件，默认 false	true
templateDirectory	Mustache 模板所在目录	src/main/resources/templates
templateResourcePath	Mustache 模板资源路径，优先于 templateDirectory	classpath:/templates
engine	使用的模板引擎，默认 mustache，可选 handlebars	mustache
auth	远程获取 OpenAPI 定义时添加的授权头	“Authorization: Bearer xyz”
configurationFile	指定 JSON 格式的配置文件路径	config.json
skipOverwrite	是否跳过已存在文件的覆盖，默认 false	true
apiPackage	生成的 API 类所在的包	com.example.api
modelPackage	生成的模型类所在的包	com.example.model
invokerPackage	生成的调用类所在的包	com.example.invoker
packageName	生成对象的默认包名	com.example
groupId	在 pom.xml 或 build.gradle 中设置项目的 Group ID	com.example
artifactId	在 pom.xml 或 build.gradle 中设置项目的 Artifact ID	openapi-client
artifactVersion	在 pom.xml 或 build.gradle 中设置项目的版本	1.0.0
library	选择库模板（子模板）	jersey2
modelNamePrefix	为模型类和枚举类设置前缀	My
modelNameSuffix	为模型类和枚举类设置后缀	Dto
apiNameSuffix	为 API 类设置后缀	Controller
ignoreFileOverride	指定 .openapi-generator-ignore 文件路径	.openapi-generator-ignore
httpUserAgent	自定义 User-Agent 头信息	MyGenerator/1.0
removeOperationIdPrefix	移除 operationId 前缀	true
skipOperationExample	跳过 API 示例生成	true
logToStderr	记录日志到标准错误输出	true
enablePostProcessFile	启用文件后处理钩子	true
skipValidateSpec	是否跳过规范文件的验证，默认 false	true
strictSpec	是否严格遵循 OpenAPI 规范	true
openapiNormalizer	设定 OpenAPI 规范归一化规则	RULE_1=true,RULE_2=original
generateAliasAsModel	是否将别名（数组、映射）作为模型生成	true
supportingFilesToGenerate	指定要生成的支持文件列表，以逗号分隔，默认生成所有支持文件	APIUtil.java
configOptions	生成器特定的参数映射	{“dateLibrary”:“java8”}
instantiationTypes	设定实例化类型映射	array=ArrayList,map=HashMap
importMappings	设定类与其 import 之间的映射	MyType=com.example.MyType
typeMappings	设定 OpenAPI 类型与生成代码类型之间的映射	string=String
schemaMappings	设定架构名称的映射	schema_a=Cat
nameMappings	设定属性名称的映射	property_a=firstProperty
modelNameMappings	设定模型名称的映射	model_a=FirstModel
parameterNameMappings	设定参数名称的映射	param_a=first_parameter
generateApis	是否生成 API 代码，默认 true	true
generateModels	是否生成模型代码，默认 true	true
generateSupportingFiles	是否生成支持文件，默认 true	true
generateModelTests	是否生成模型测试代码	true
generateModelDocumentation	是否生成模型文档	true
generateApiTests	是否生成 API 测试代码	true
generateApiDocumentation	是否生成 API 文档	true
skip	是否跳过代码生成	false
dryRun	是否启用 dry-run 模式，不生成文件，仅显示摘要	true
globalProperties	设定全局属性，影响所有代码生成阶段	{“apiDocs”:“false”}
serverVariableOverrides	指定服务器变量的重写	{“basePath”:“/v2”}
reservedWordsMappings	保留关键字的映射	id=identifier
generateModelTests	是否生成模型测试代码	true
generateModelDocumentation	是否生成模型文档	true
generateApiTests	是否生成 API 测试代码	true
generateApiDocumentation	是否生成 API 文档	true
addCompileSourceRoot	是否将输出目录添加到编译源	true
addTestCompileSourceRoot	是否将输出目录添加到测试编译源	false
environmentVariables	已废弃，请使用 globalProperties	N/A

上面标红的参数为常用的参数，其中 supportingFilesToGenerate , configOptions 是复合类型的参数，具体要怎么配置我们需要去查看Generator的源码才能知道一二。

supportingFilesToGenerate 参数说明

下载源代码

首先大家需要从OpenAPI Generator Github Repository下载源代码。

arsenal@txzq1899:~/Workspace$ git clone git@github.com:OpenAPITools/openapi-generator.git

在IDE中打开项目（推荐使用VSCode）

要了解supportingFilesToGenerate要如何配置，我们需要从源码中寻找答案，以Spring为例，如果我们是生成Spring的代码，我们需要查看SpringCodegen.java这个文件。

打开SpringCodegen.java

通过Ctrl + F 查找：supportingFiles.add ， 我们可以看到总共有18处。

PS：我们可以看到 org.openapitools.codegen.languages 这个package下边有很多的Codegen，不同的Codegen其supportingFiles是不一样的，大家可自行研究。

SpringCodeGen supportingFiles 整理

根据 SpringCodegen 的 processOpts() 方法及相关逻辑，可以整理出 supportingFiles 里有哪些文件，以及它们在什么情况下会被添加。以下是分析结果：

FileName	Condition（条件）
pom-sb3.mustache → pom.xml	useSpringBoot3 == true
pom.mustache → pom.xml	useSpringBoot3 == false
README.mustache → README.md	总是添加
swagger-ui.mustache → swagger-ui.html	useSwaggerUI == true 且 selectedDocumentationProviderRequiresSwaggerUiBootstrap() == true
openapi2SpringBoot.mustache → OpenApiGeneratorApplication.java	interfaceOnly == false 且 library == SPRING_BOOT
SpringBootTest.mustache → OpenApiGeneratorApplicationTests.java	interfaceOnly == false 且 library == SPRING_BOOT
RFC3339DateFormat.mustache → RFC3339DateFormat.java	interfaceOnly == false 且 library == SPRING_BOOT
apiKeyRequestInterceptor.mustache → ApiKeyRequestInterceptor.java	library == SPRING_CLOUD_LIBRARY
clientPropertiesConfiguration.mustache → ClientPropertiesConfiguration.java	library == SPRING_CLOUD_LIBRARY 且 OpenAPI 配置了 OAuth 方法
clientConfiguration.mustache → ClientConfiguration.java	library == SPRING_CLOUD_LIBRARY
application.mustache → application.properties	interfaceOnly == false 且 library == SPRING_BOOT
homeController.mustache → HomeController.java	interfaceOnly == false 且 library == SPRING_BOOT
openapi.mustache → openapi.yaml	interfaceOnly == false 且 library == SPRING_BOOT
springdocDocumentationConfig.mustache → SpringDocConfiguration.java	interfaceOnly == false 且 library == SPRING_BOOT 且 reactive == false 且 apiFirst == false 且 getDocumentationProvider() == SPRINGDOC
openapiDocumentationConfig.mustache → SpringFoxConfiguration.java	interfaceOnly == false 且 library == SPRING_BOOT 且 reactive == false 且 apiFirst == false 且 getDocumentationProvider() == SPRINGFOX
httpInterfacesConfiguration.mustache → HttpInterfacesAbstractConfigurator.java	library == SPRING_HTTP_INTERFACE
apiUtil.mustache → ApiUtil.java	library == SPRING_BOOT
converter.mustache → EnumConverterConfiguration.java	interfaceOnly == false 且 library == SPRING_BOOT 且 openAPI 里包含 enum
apiDelegate.mustache → Delegate.java	delegatePattern == true 且 delegateMethod == false

通常来讲，我们第一次运行Codegen时，不需要配置supportingFilesToGenerate，Codegen会根据上面的条件来默认生成一些文件，比如：

• README.MD
• pom.xml（后续不能覆盖）
• SpringDocConfiguration.java
• OpenApiGeneratorApplication.java
• HomeController.java
• openapi.yaml（通常我们会删除该文件，后续也不再生成）
  等，在项目初始化完后再根据项目实际情况对基础框架代码进行相应的调整，比如 pom.xml 文件，第一次生成后，我们会引用一些其它的项目依赖，我们肯定会对pom.xml进行修改，那后面这个文件就不能被覆盖，我们就需要配置supportingFilesToGenerate，在这里显示指定要生成的文件。比如：APIUtil.java，或者 空，这样就会避免覆盖 pom.xml, SpringbootApplication入口文件等。

上面这些文件的生成，会参考 modules/openapi-generator/src/main/resources/JavaSpring 目录下的模板文件，比如 apiUtil.mustache

ConfigOptions 参数解析

大家可以从以下的源码中看到ConfigOptions都有哪些参数
modules/openapi-generator-maven-plugin/src/main/java/org/openapitools/codegen/plugin/CodeGenMojo.java

ConfigOptions 参数分析

configOptions 包含了一系列 键值对 (Key-Value Pairs)，每个键代表一个 OpenAPI 代码生成器的配置项，而值则是相应的设定。以下是主要的 configOptions 及其功能：

参数名称	功能
instantiation-types	定义对象的实例化类型映射，例如将 array 映射为 ArrayList
import-mappings	定义模型类的 Java 包路径映射，例如 LocalDateTime -> java.time.LocalDateTime
schema-mappings	定义 OpenAPI schema 类型到 Java 类型的映射
inline-schema-name-mappings	自定义内联 Schema 的命名映射
inline-schema-options	配置是否允许内联 Schema
openapi-normalizer	配置 OpenAPI 规范的标准化规则
type-mappings	OpenAPI 数据类型到 Java 类型的映射，例如 integer -> Integer
language-specific-primitives	指定代码生成器支持的原生数据类型，例如 BigDecimal, LocalDateTime
openapi-generator-ignore-list	配置忽略的 OpenAPI 代码生成文件
additional-properties	自定义代码生成的额外属性，决定生成代码的特性
server-variables	配置服务器 URL 变量
reserved-words-mappings	配置保留关键字的替代映射，例如 class -> clazz
name-mappings	自定义生成的 API、模型或参数的名称
parameter-name-mappings	配置参数名称的映射规则
model-name-mappings	配置模型名称的映射规则
enum-name-mappings	配置枚举名称的映射规则
operation-id-name-mappings	配置 OpenAPI 操作 ID 的映射规则
source-folder	代码生成的源代码目录

有关使用SpringBoot集成Openapi-generator-maven插件的详细配置说明到这里就完成了。大家可以收藏本文章，并仔细研究每一个配置，根据项目的实际情况进行配置。

关注我的公众号

欢迎大家关注、点赞、转发，一起交流软件开发、架构设计、云原生技术。