[kotlin] Added path sanitization in javadoc comments

.github/workflows/samples-kotlin-client.yaml

@@ -65,6 +65,7 @@ jobs:
           - samples/client/echo_api/kotlin-jvm-spring-3-restclient
           - samples/client/petstore/kotlin-name-parameter-mappings
           - samples/client/others/kotlin-jvm-okhttp-parameter-tests
+          - samples/client/others/kotlin-jvm-okhttp-path-comments
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-java@v4

bin/configs/kotlin-jvm-okhttp-path-comments.yaml

@@ -0,0 +1,8 @@
+generatorName: kotlin
+outputDir: samples/client/others/kotlin-jvm-okhttp-path-comments
+library: jvm-okhttp4
+inputSpec: modules/openapi-generator/src/test/resources/3_0/kotlin/issue20618-path-comments.yaml
+templateDir: modules/openapi-generator/src/main/resources/kotlin-client
+additionalProperties:
+  artifactId: kotlin-petstore-okhttp4-path-comments
+

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/KotlinClientCodegen.java

@@ -40,6 +40,35 @@
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
+import com.samskivert.mustache.Mustache;
+import lombok.Getter;
+import lombok.Setter;
+import org.apache.commons.lang3.StringUtils;
+import org.openapitools.codegen.CliOption;
+import org.openapitools.codegen.CodegenConstants;
+import org.openapitools.codegen.CodegenModel;
+import org.openapitools.codegen.CodegenOperation;
+import org.openapitools.codegen.CodegenParameter;
+import org.openapitools.codegen.CodegenProperty;
+import org.openapitools.codegen.CodegenType;
+import org.openapitools.codegen.SupportingFile;
+import org.openapitools.codegen.VendorExtension;
+import org.openapitools.codegen.meta.features.ClientModificationFeature;
+import org.openapitools.codegen.meta.features.DocumentationFeature;
+import org.openapitools.codegen.meta.features.GlobalFeature;
+import org.openapitools.codegen.meta.features.ParameterFeature;
+import org.openapitools.codegen.meta.features.SchemaSupportFeature;
+import org.openapitools.codegen.meta.features.SecurityFeature;
+import org.openapitools.codegen.meta.features.WireFormatFeature;
+import org.openapitools.codegen.model.ModelMap;
+import org.openapitools.codegen.model.ModelsMap;
+import org.openapitools.codegen.model.OperationMap;
+import org.openapitools.codegen.model.OperationsMap;
+import org.openapitools.codegen.templating.mustache.ReplaceAllLambda;
+import org.openapitools.codegen.utils.ProcessUtils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
 import static java.util.Collections.sort;
 
 public class KotlinClientCodegen extends AbstractKotlinCodegen {
@@ -534,6 +563,10 @@ public void processOpts() {
             }
             writer.write(content);
         });
+        // When a path is added to a Javadoc, if it ends with a `/*` is will cause a compiler error
+        // as the parser interrupts that as a start of a multiline comment.
+        // We replace paths like `/v1/foo/*` with `/v1/foo/<*>` to avoid this
+        additionalProperties.put("sanitizePathComment", new ReplaceAllLambda("\\/\\*", "/<*>"));
     }
 
     private void processDateLibrary() {

modules/openapi-generator/src/main/resources/kotlin-client/libraries/jvm-ktor/api.mustache

@@ -43,7 +43,7 @@ import com.fasterxml.jackson.databind.ObjectMapper
 
     {{#operation}}
         /**
-        * {{{httpMethod}}} {{{path}}}
+        * {{{httpMethod}}} {{#sanitizePathComment}}{{{path}}}{{/sanitizePathComment}}
         * {{summary}}
         * {{notes}}
         {{#allParams}} * @param {{{paramName}}} {{description}} {{^required}}(optional{{#defaultValue}}, default to {{{.}}}{{/defaultValue}}){{/required}}

modules/openapi-generator/src/main/resources/kotlin-client/libraries/jvm-okhttp/api.mustache

@@ -123,7 +123,7 @@ import {{packageName}}.infrastructure.toMultiValue
     {{/isEnum}}
     {{/allParams}}
     /**
-     * {{{httpMethod}}} {{{path}}}
+     * {{{httpMethod}}} {{#sanitizePathComment}}{{{path}}}{{/sanitizePathComment}}
      * {{summary}}
      * {{notes}}
      {{#allParams}}* @param {{{paramName}}} {{description}}{{^required}} (optional{{#defaultValue}}, default to {{{.}}}{{/defaultValue}}){{/required}}{{#required}}{{#defaultValue}} (default to {{{.}}}){{/defaultValue}}{{/required}}
@@ -161,7 +161,7 @@ import {{packageName}}.infrastructure.toMultiValue
     }
 
     /**
-     * {{{httpMethod}}} {{{path}}}
+     * {{{httpMethod}}} {{#sanitizePathComment}}{{{path}}}{{/sanitizePathComment}}
      * {{summary}}
      * {{notes}}
      {{#allParams}}* @param {{{paramName}}} {{description}}{{^required}} (optional{{#defaultValue}}, default to {{{.}}}{{/defaultValue}}){{/required}}{{#required}}{{#defaultValue}} (default to {{{.}}}){{/defaultValue}}{{/required}}

modules/openapi-generator/src/main/resources/kotlin-client/libraries/jvm-retrofit2/api.mustache

@@ -131,7 +131,7 @@ import okhttp3.MultipartBody
     {{/isEnum}}
     {{/allParams}}
     /**
-     * {{{httpMethod}}} {{{path}}}
+     * {{{httpMethod}}} {{#sanitizePathComment}}{{{path}}}{{/sanitizePathComment}}
      * {{summary}}
      * {{notes}}
      * Responses:{{#responses}}

modules/openapi-generator/src/main/resources/kotlin-client/libraries/jvm-vertx/api.mustache

@@ -88,7 +88,7 @@ import {{packageName}}.infrastructure.*
     {{/isEnum}}
     {{/allParams}}
     /**
-     * {{{httpMethod}}} {{{path}}}
+     * {{{httpMethod}}} {{#sanitizePathComment}}{{{path}}}{{/sanitizePathComment}}
      * {{summary}}
      * {{notes}}
      {{#allParams}}* @param {{{paramName}}} {{description}}{{^required}} (optional{{#defaultValue}}, default to {{{.}}}{{/defaultValue}}){{/required}}{{#required}}{{#defaultValue}} (default to {{{.}}}){{/defaultValue}}{{/required}}
@@ -123,7 +123,7 @@ import {{packageName}}.infrastructure.*
     }
 
     /**
-     * {{{httpMethod}}} {{{path}}}
+     * {{{httpMethod}}} {{#sanitizePathComment}}{{{path}}}{{/sanitizePathComment}}
      * {{summary}}
      * {{notes}}
      {{#allParams}}* @param {{{paramName}}} {{description}}{{^required}} (optional{{#defaultValue}}, default to {{{.}}}{{/defaultValue}}){{/required}}{{#required}}{{#defaultValue}} (default to {{{.}}}){{/defaultValue}}{{/required}}

modules/openapi-generator/src/main/resources/kotlin-client/libraries/jvm-volley/api.mustache

@@ -37,7 +37,7 @@ import {{packageName}}.infrastructure.CollectionFormats.*
 
     {{#operation}}
     /**
-     * {{{httpMethod}}} {{{path}}}
+     * {{{httpMethod}}} {{#sanitizePathComment}}{{{path}}}{{/sanitizePathComment}}
      * {{summary}}
      * {{notes}}
      {{#allParams}}* @param {{{paramName}}} {{description}}{{^required}} (optional{{#defaultValue}}, default to {{{.}}}{{/defaultValue}}){{/required}}{{#required}}{{#defaultValue}} (default to {{{.}}}){{/defaultValue}}{{/required}}

modules/openapi-generator/src/test/resources/3_0/kotlin/issue20618-path-comments.yaml

@@ -0,0 +1,41 @@
+# See: https://github.com/OpenAPITools/openapi-generator/pull/20618#issuecomment-2690874645
+openapi: 3.0.0
+servers:
+  - url: 'https://example.org/v1'
+info:
+  description: >-
+    Example created
+  version: 1.0.0
+  title: OpenAPI Stuff API created to reproduce issue
+  license:
+    name: Apache-2.0
+    url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
+tags:
+  - name: stuff
+    description: All about the stuff
+security:
+  - bearerAuth: []
+paths:
+  /foo/*:
+    get:
+      tags:
+        - stuff
+      summary: Finds stuff
+      description: Finds stuff
+      operationId: findStuff
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT

samples/client/others/kotlin-jvm-okhttp-path-comments/.openapi-generator-ignore

@@ -0,0 +1,23 @@
+# OpenAPI Generator Ignore
+# Generated by openapi-generator https://github.com/openapitools/openapi-generator
+
+# Use this file to prevent files from being overwritten by the generator.
+# The patterns follow closely to .gitignore or .dockerignore.
+
+# As an example, the C# client generator defines ApiClient.cs.
+# You can make changes and tell OpenAPI Generator to ignore just this file by uncommenting the following line:
+#ApiClient.cs
+
+# You can match any string of characters against a directory, file or extension with a single asterisk (*):
+#foo/*/qux
+# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux
+
+# You can recursively match patterns against a directory, file or extension with a double asterisk (**):
+#foo/**/qux
+# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux
+
+# You can also negate patterns with an exclamation (!).
+# For example, you can ignore all files in a docs folder with the file extension .md:
+#docs/*.md
+# Then explicitly reverse the ignore rule for a single file:
+#!docs/README.md

samples/client/others/kotlin-jvm-okhttp-path-comments/.openapi-generator/FILES

@@ -0,0 +1,28 @@
+README.md
+build.gradle
+docs/FindStuff200Response.md
+docs/StuffApi.md
+gradle/wrapper/gradle-wrapper.jar
+gradle/wrapper/gradle-wrapper.properties
+gradlew
+gradlew.bat
+settings.gradle
+src/main/kotlin/org/openapitools/client/apis/StuffApi.kt
+src/main/kotlin/org/openapitools/client/infrastructure/ApiAbstractions.kt
+src/main/kotlin/org/openapitools/client/infrastructure/ApiClient.kt
+src/main/kotlin/org/openapitools/client/infrastructure/ApiResponse.kt
+src/main/kotlin/org/openapitools/client/infrastructure/BigDecimalAdapter.kt
+src/main/kotlin/org/openapitools/client/infrastructure/BigIntegerAdapter.kt
+src/main/kotlin/org/openapitools/client/infrastructure/ByteArrayAdapter.kt
+src/main/kotlin/org/openapitools/client/infrastructure/Errors.kt
+src/main/kotlin/org/openapitools/client/infrastructure/LocalDateAdapter.kt
+src/main/kotlin/org/openapitools/client/infrastructure/LocalDateTimeAdapter.kt
+src/main/kotlin/org/openapitools/client/infrastructure/OffsetDateTimeAdapter.kt
+src/main/kotlin/org/openapitools/client/infrastructure/PartConfig.kt
+src/main/kotlin/org/openapitools/client/infrastructure/RequestConfig.kt
+src/main/kotlin/org/openapitools/client/infrastructure/RequestMethod.kt
+src/main/kotlin/org/openapitools/client/infrastructure/ResponseExtensions.kt
+src/main/kotlin/org/openapitools/client/infrastructure/Serializer.kt
+src/main/kotlin/org/openapitools/client/infrastructure/URIAdapter.kt
+src/main/kotlin/org/openapitools/client/infrastructure/UUIDAdapter.kt
+src/main/kotlin/org/openapitools/client/models/FindStuff200Response.kt

samples/client/others/kotlin-jvm-okhttp-path-comments/.openapi-generator/VERSION

@@ -0,0 +1 @@
+7.13.0-SNAPSHOT

samples/client/others/kotlin-jvm-okhttp-path-comments/README.md

@@ -0,0 +1,66 @@
+# org.openapitools.client - Kotlin client library for OpenAPI Stuff API created to reproduce issue
+
+Example created
+
+## Overview
+This API client was generated by the [OpenAPI Generator](https://openapi-generator.tech) project.  By using the [openapi-spec](https://github.com/OAI/OpenAPI-Specification) from a remote server, you can easily generate an API client.
+
+- API version: 1.0.0
+- Package version: 
+- Generator version: 7.13.0-SNAPSHOT
+- Build package: org.openapitools.codegen.languages.KotlinClientCodegen
+
+## Requires
+
+* Kotlin 1.7.21
+* Gradle 7.5
+
+## Build
+
+First, create the gradle wrapper script:
+
+```
+gradle wrapper
+```
+
+Then, run:
+
+```
+./gradlew check assemble
+```
+
+This runs all tests and packages the library.
+
+## Features/Implementation Notes
+
+* Supports JSON inputs/outputs, File inputs, and Form inputs.
+* Supports collection formats for query parameters: csv, tsv, ssv, pipes.
+* Some Kotlin and Java types are fully qualified to avoid conflicts with types defined in OpenAPI definitions.
+* Implementation of ApiClient is intended to reduce method counts, specifically to benefit Android targets.
+
+<a id="documentation-for-api-endpoints"></a>
+## Documentation for API Endpoints
+
+All URIs are relative to *https://example.org/v1*
+
+| Class | Method | HTTP request | Description |
+| ------------ | ------------- | ------------- | ------------- |
+| *StuffApi* | [**findStuff**](docs/StuffApi.md#findstuff) | **GET** /foo/* | Finds stuff |
+
+
+<a id="documentation-for-models"></a>
+## Documentation for Models
+
+ - [org.openapitools.client.models.FindStuff200Response](docs/FindStuff200Response.md)
+
+
+<a id="documentation-for-authorization"></a>
+## Documentation for Authorization
+
+
+Authentication schemes defined for the API:
+<a id="bearerAuth"></a>
+### bearerAuth
+
+- **Type**: HTTP Bearer Token authentication (JWT)
+

samples/client/others/kotlin-jvm-okhttp-path-comments/build.gradle

@@ -0,0 +1,62 @@
+group 'org.openapitools'
+version '1.0.0'
+
+wrapper {
+    gradleVersion = '8.7'
+    distributionUrl = "https://services.gradle.org/distributions/gradle-$gradleVersion-all.zip"
+}
+
+buildscript {
+    ext.kotlin_version = '1.9.23'
+    ext.spotless_version = "6.25.0"
+
+    repositories {
+        maven { url "https://repo1.maven.org/maven2" }
+    }
+    dependencies {
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+        classpath "com.diffplug.spotless:spotless-plugin-gradle:$spotless_version"
+    }
+}
+
+apply plugin: 'kotlin'
+apply plugin: 'maven-publish'
+apply plugin: 'com.diffplug.spotless'
+
+repositories {
+    maven { url "https://repo1.maven.org/maven2" }
+}
+
+// Use spotless plugin to automatically format code, remove unused import, etc
+// To apply changes directly to the file, run `gradlew spotlessApply`
+// Ref: https://github.com/diffplug/spotless/tree/main/plugin-gradle
+spotless {
+    // comment out below to run spotless as part of the `check` task
+    enforceCheck false
+
+    format 'misc', {
+        // define the files (e.g. '*.gradle', '*.md') to apply `misc` to
+        target '.gitignore'
+
+        // define the steps to apply to those files
+        trimTrailingWhitespace()
+        indentWithSpaces() // Takes an integer argument if you don't like 4
+        endWithNewline()
+    }
+    kotlin {
+        ktfmt()
+    }
+}
+
+test {
+    useJUnitPlatform()
+}
+
+dependencies {
+    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
+    implementation "org.jetbrains.kotlin:kotlin-reflect:$kotlin_version"
+    implementation "com.squareup.moshi:moshi-kotlin:1.15.1"
+    implementation "com.squareup.moshi:moshi-adapters:1.15.1"
+    implementation "com.squareup.okhttp3:okhttp:4.12.0"
+    testImplementation "io.kotlintest:kotlintest-runner-junit5:3.4.2"
+}

samples/client/others/kotlin-jvm-okhttp-path-comments/docs/FindStuff200Response.md

@@ -0,0 +1,10 @@
+
+# FindStuff200Response
+
+## Properties
+| Name | Type | Description | Notes |
+| ------------ | ------------- | ------------- | ------------- |
+| **id** | **kotlin.String** |  |  [optional] |
+
+
+