[MAVEN PLUGIN; GRADLE-PLUGIN] - Add KDoc/Javadoc to the Gradle plugin and integrate Dokka so IDEs show helpful tooltips; fix missing parameter wiring; improve merged-spec handling to match the Maven plugin

modules/openapi-generator-gradle-plugin/build.gradle

@@ -8,6 +8,7 @@ plugins {
     id("java-gradle-plugin")
     id("maven-publish")
     id("org.gradle.kotlin.kotlin-dsl") version "5.2.0"
+    id("org.jetbrains.dokka") version "1.9.20"
     id("org.jetbrains.kotlin.jvm") version "2.0.21"
     id("signing")
 }
@@ -73,6 +74,12 @@ tasks.withType(Javadoc).configureEach {
     }
 }
 
+// Use Dokka to generate KDoc-based Javadoc so IntelliJ shows tooltips for plugin properties
+tasks.named("javadocJar") {
+    dependsOn(tasks.named("dokkaJavadoc"))
+    from(tasks.named("dokkaJavadoc").map { it.outputs })
+}
+
 tasks.withType(CloseNexusStagingRepository).configureEach {
     onlyIf { nexusPublishing.useStaging.get() }
 }

modules/openapi-generator-gradle-plugin/src/main/kotlin/org/openapitools/generator/gradle/plugin/OpenApiGeneratorPlugin.kt

@@ -101,6 +101,10 @@ class OpenApiGeneratorPlugin : Plugin<Project> {
                     inputSpec.set(generate.inputSpec)
                     inputSpecRootDirectory.set(generate.inputSpecRootDirectory)
                     inputSpecRootDirectorySkipMerge.set(generate.inputSpecRootDirectorySkipMerge)
+                    mergedFileName.set(generate.mergedFileName)
+                    mergedFileInfoName.set(generate.mergedFileInfoName)
+                    mergedFileInfoDescription.set(generate.mergedFileInfoDescription)
+                    mergedFileInfoVersion.set(generate.mergedFileInfoVersion)
                     remoteInputSpec.set(generate.remoteInputSpec)
                     templateDir.set(generate.templateDir)
                     templateResourcePath.set(generate.templateResourcePath)
@@ -127,6 +131,8 @@ class OpenApiGeneratorPlugin : Plugin<Project> {
                     nameMappings.set(generate.nameMappings)
                     modelNameMappings.set(generate.modelNameMappings)
                     parameterNameMappings.set(generate.parameterNameMappings)
+                    enumNameMappings.set(generate.enumNameMappings)
+                    operationIdNameMappings.set(generate.operationIdNameMappings)
                     openapiNormalizer.set(generate.openapiNormalizer)
                     invokerPackage.set(generate.invokerPackage)
                     groupId.set(generate.groupId)
@@ -157,6 +163,9 @@ class OpenApiGeneratorPlugin : Plugin<Project> {
                     engine.set(generate.engine)
                     cleanupOutput.set(generate.cleanupOutput)
                     dryRun.set(generate.dryRun)
+                    strictSpec.set(generate.strictSpec)
+                    minimalUpdate.set(generate.minimalUpdate)
+                    generateRecursiveDependentModels.set(generate.generateRecursiveDependentModels)
                     workerIsolation.set(generate.workerIsolation)
                     maxWorkerHeapSize.set(generate.maxWorkerHeapSize)
                 }

modules/openapi-generator-gradle-plugin/src/main/kotlin/org/openapitools/generator/gradle/plugin/extensions/OpenApiGeneratorGenerateExtension.kt

@@ -38,6 +38,7 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
 
     /**
      * Whether an input specification should be validated upon generation.
+     * Defaults to `true`.
      */
     val validateSpec = project.objects.property<Boolean>()
 
@@ -75,6 +76,30 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
      */
     val inputSpecRootDirectorySkipMerge = project.objects.property<Boolean>()
 
+    /**
+     * The name of the merged spec file produced when [inputSpecRootDirectory] is used.
+     * Defaults to `"merged"`.
+     */
+    val mergedFileName = project.objects.property<String>()
+
+    /**
+     * Title placed in the `info.title` field of the merged spec. Defaults to `"merged spec"`.
+     * Only used when [inputSpecRootDirectory] is set.
+     */
+    val mergedFileInfoName = project.objects.property<String>()
+
+    /**
+     * Description placed in the `info.description` field of the merged spec. Defaults to `"merged spec"`.
+     * Only used when [inputSpecRootDirectory] is set.
+     */
+    val mergedFileInfoDescription = project.objects.property<String>()
+
+    /**
+     * Version placed in the `info.version` field of the merged spec. Defaults to `"1.0.0"`.
+     * Only used when [inputSpecRootDirectory] is set.
+     */
+    val mergedFileInfoVersion = project.objects.property<String>()
+
     /**
      * The remote Open API 2.0/3.x specification URL location.
      */
@@ -189,7 +214,11 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
     val inlineSchemaNameMappings = project.objects.mapProperty<String, String>()
 
     /**
-     * Specifies options for inline schemas
+     * Key/value options controlling how inline schemas are handled during generation.
+     *
+     * Common keys: `RESOLVE_INLINE_ENUMS` (promote inline enums to top-level models),
+     * `ARRAY_ITEMS_SUFFIX`, `MAP_ITEMS_SUFFIX`. Run `config-help -g {generatorName}` for the
+     * full list of supported options.
      */
     val inlineSchemaOptions = project.objects.mapProperty<String, String>()
 
@@ -219,7 +248,12 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
     val operationIdNameMappings = project.objects.mapProperty<String, String>()
 
     /**
-     * Specifies mappings (rules) in OpenAPI normalizer
+     * Key/value rules passed to the OpenAPI normalizer, which pre-processes the parsed spec
+     * before code generation begins.
+     *
+     * Example rules: `REFACTOR_ALLOF_WITH_PROPERTIES_ONLY=true`,
+     * `REMOVE_ANYOF_ONEOF_AND_KEEP_PROPERTIES_ONLY=true`. See the OpenAPI Generator docs for
+     * the full list of normalizer rules.
      */
     val openapiNormalizer = project.objects.mapProperty<String, String>()
 
@@ -330,6 +364,7 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
      *
      * For more control over generation of individual files, configure an ignore file and
      * refer to it via [ignoreFileOverride].
+     * Defaults to `true`.
      */
     val generateModelTests = project.objects.property<Boolean>()
 
@@ -340,6 +375,7 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
      *
      * For more control over generation of individual files, configure an ignore file and
      * refer to it via [ignoreFileOverride].
+     * Defaults to `true`.
      */
     val generateModelDocumentation = project.objects.property<Boolean>()
 
@@ -350,6 +386,7 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
      *
      * For more control over generation of individual files, configure an ignore file and
      * refer to it via [ignoreFileOverride].
+     * Defaults to `true`.
      */
     val generateApiTests = project.objects.property<Boolean>()
 
@@ -360,11 +397,12 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
      *
      * For more control over generation of individual files, configure an ignore file and
      * refer to it via [ignoreFileOverride].
+     * Defaults to `true`.
      */
     val generateApiDocumentation = project.objects.property<Boolean>()
 
     /**
-     * To write all log messages (not just errors) to STDOUT
+     * To write all log messages (not just errors) to STDOUT. Defaults to `false`.
      */
     val logToStderr = project.objects.property<Boolean>()
 
@@ -373,18 +411,40 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
      * This only enables the post-processor. To define the post-processing command, define an environment variable such as
      * LANG_POST_PROCESS_FILE (e.g. GO_POST_PROCESS_FILE, SCALA_POST_PROCESS_FILE). Please open an issue if your target
      * generator does not support this functionality.
+     * Defaults to `false`.
      */
     val enablePostProcessFile = project.objects.property<Boolean>()
 
     /**
      * To skip spec validation. When true, we will skip the default behavior of validating a spec before generation.
+     * Defaults to `false`.
      */
     val skipValidateSpec = project.objects.property<Boolean>()
 
+    /**
+     * When `true`, applies strict validation against the OpenAPI specification, failing on any deviation.
+     * Defaults to `false`.
+     */
+    val strictSpec = project.objects.property<Boolean>()
+
+    /**
+     * When `true`, only writes output files that have changed relative to an existing generated output.
+     * Reduces unnecessary file churn in version control. Defaults to `false`.
+     */
+    val minimalUpdate = project.objects.property<Boolean>()
+
+    /**
+     * When `true`, recursively generates all models that the selected models depend on,
+     * even if those dependent models were not explicitly listed for generation.
+     * Only relevant when [modelFilesConstrainedTo] is configured. Defaults to `false`.
+     */
+    val generateRecursiveDependentModels = project.objects.property<Boolean>()
+
     /**
      * To generate alias (array, list, map) as model. When false, top-level objects defined as array, list, or map will result in those
      * definitions generated as top-level Array-of-items, List-of-items, Map-of-items definitions.
      * When true, A model representation either containing or extending the array,list,map (depending on specific generator implementation) will be generated.
+     * Defaults to `false`.
      */
     val generateAliasAsModel = project.objects.property<Boolean>()
 
@@ -400,12 +460,13 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
 
     /**
      * Defines whether the output dir should be cleaned up before generating the output.
-     *
+     * Defaults to `false`.
      */
     val cleanupOutput = project.objects.property<Boolean>()
 
     /**
      * Defines whether the generator should run in dry-run mode.
+     * Defaults to `false`.
      */
     val dryRun = project.objects.property<Boolean>()
 
@@ -439,6 +500,7 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
     fun applyDefaults() {
         releaseNote.convention("Minor update")
         inputSpecRootDirectorySkipMerge.convention(false)
+        mergedFileName.convention("merged")
         modelNamePrefix.convention("")
         modelNameSuffix.convention("")
         apiNameSuffix.convention("")
@@ -454,6 +516,12 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
         generateAliasAsModel.convention(false)
         cleanupOutput.convention(false)
         dryRun.convention(false)
+        mergedFileInfoName.convention("merged spec")
+        mergedFileInfoDescription.convention("merged spec")
+        mergedFileInfoVersion.convention("1.0.0")
+        strictSpec.convention(false)
+        minimalUpdate.convention(false)
+        generateRecursiveDependentModels.convention(false)
     }
 
     // ========================================================================

modules/openapi-generator-gradle-plugin/src/main/kotlin/org/openapitools/generator/gradle/plugin/extensions/OpenApiGeneratorMetaExtension.kt

@@ -29,6 +29,7 @@ import org.gradle.kotlin.dsl.property
 open class OpenApiGeneratorMetaExtension(private val project: Project) {
     /**
      * The human-readable generator name of the newly created template generator.
+     * Defaults to `"default"`.
      */
     val generatorName: Property<String> = project.objects.property()
 

modules/openapi-generator-gradle-plugin/src/main/kotlin/org/openapitools/generator/gradle/plugin/extensions/OpenApiGeneratorValidateExtension.kt

@@ -41,11 +41,13 @@ open class OpenApiGeneratorValidateExtension(private val project: Project) {
 
     /**
      * Whether to offer recommendations related to the validated specification document.
+     * Defaults to `true`.
      */
     val recommend: Property<Boolean> = project.objects.property<Boolean>().convention(true)
 
     /**
      * Whether to treat warnings as errors and fail the task.
+     * Defaults to `false`.
      */
     val treatWarningsAsErrors: Property<Boolean> = project.objects.property<Boolean>().convention(false)