[kotlin] Added path sanitization in javadoc comments (#20767)

* [kotlin] Added path sanitization in javadoc comments

* added sample as regression test

* Added samples/client/others/kotlin-jvm-okhttp-path-comments to github workflow

Author: ranger-ross

.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 {
@@ -536,6 +565,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