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插件配置详解

• 参数说明
• supportingFilesToGenerate 参数说明
• • 下载源代码
  • 在IDE中打开项目（推荐使用VSCode）
  • • 打开SpringCodegen.java
    • SpringCodeGen supportingFiles 整理
    • ConfigOptions 参数解析
    • • ConfigOptions 参数分析
      • 关注我的公众号

        上一篇文章介绍了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插件的详细配置说明到这里就完成了。大家可以收藏本文章，并仔细研究每一个配置，根据项目的实际情况进行配置。

            关注我的公众号

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