[MARKDOWN] Fix issue 6089 with property and parameter names (#6105)

Co-authored-by: Jim Schubert <james.schubert@gmail.com>

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

@@ -1,21 +1,18 @@
 package org.openapitools.codegen.languages;
 
-import org.openapitools.codegen.*;
+import org.openapitools.codegen.CodegenConfig;
-import io.swagger.models.properties.ArrayProperty;
+import org.openapitools.codegen.CodegenType;
-import io.swagger.models.properties.MapProperty;
+import org.openapitools.codegen.DefaultCodegen;
-import io.swagger.models.properties.Property;
+import org.openapitools.codegen.SupportingFile;
-import io.swagger.models.parameters.Parameter;
-
-import java.io.File;
-import java.util.*;
-
-import org.apache.commons.lang3.StringUtils;
-
 import org.openapitools.codegen.meta.GeneratorMetadata;
 import org.openapitools.codegen.meta.Stability;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import java.io.File;
+
+import static org.openapitools.codegen.utils.StringUtils.escape;
+
 public class MarkdownDocumentationCodegen extends DefaultCodegen implements CodegenConfig {
     public static final String PROJECT_NAME = "projectName";
 
@@ -49,4 +46,37 @@ public class MarkdownDocumentationCodegen extends DefaultCodegen implements Code
         supportingFiles.add(new SupportingFile("README.mustache", "", "README.md"));
         // TODO: Fill this out.
     }
+
+    @Override
+    protected void initalizeSpecialCharacterMapping() {
+        // escape only those symbols that can mess up markdown
+        specialCharReplacements.put("\\", "\\\\");
+        specialCharReplacements.put("/", "\\/");
+        specialCharReplacements.put("`", "\\`");
+        specialCharReplacements.put("*", "\\*");
+        specialCharReplacements.put("_", "\\_");
+        specialCharReplacements.put("[", "\\[");
+        specialCharReplacements.put("]", "\\]");
+
+        // todo Current markdown api and model mustache templates display properties and parameters in tables. Pipe
+        //  symbol in a table can be commonly escaped with a backslash (e.g. GFM supports this). However, in some cases
+        //  it may be necessary to choose a different approach.
+        specialCharReplacements.put("|", "\\|");
+    }
+
+    /**
+     * Works identically to {@link DefaultCodegen#toParamName(String)} but doesn't camelize.
+     *
+     * @param name Codegen property object
+     * @return the sanitized parameter name
+     */
+    @Override
+    public String toParamName(String name) {
+        if (reservedWords.contains(name)) {
+            return escapeReservedWord(name);
+        } else if (((CharSequence) name).chars().anyMatch(character -> specialCharReplacements.keySet().contains("" + ((char) character)))) {
+            return escape(name, specialCharReplacements, null, null);
+        }
+        return name;
+    }
 }

samples/documentation/markdown/.openapi-generator/FILES

@@ -0,0 +1,12 @@
+Apis/PetApi.md
+Apis/StoreApi.md
+Apis/UserApi.md
+Models/ApiResponse.md
+Models/Category.md
+Models/InlineObject.md
+Models/InlineObject1.md
+Models/Order.md
+Models/Pet.md
+Models/Tag.md
+Models/User.md
+README.md

samples/documentation/markdown/Apis/PetApi.md

@@ -16,7 +16,7 @@ Method | HTTP request | Description
 
 <a name="addPet"></a>
 # **addPet**
-> Pet addPet(pet)
+> Pet addPet(Pet)
 
 Add a new pet to the store
 
@@ -24,7 +24,7 @@ Add a new pet to the store
 
 Name | Type | Description  | Notes
 ------------- | ------------- | ------------- | -------------
- **pet** | [**Pet**](..//Models/Pet.md)| Pet object that needs to be added to the store |
+ **Pet** | [**Pet**](..//Models/Pet.md)| Pet object that needs to be added to the store |
 
 ### Return type
 
@@ -41,7 +41,7 @@ Name | Type | Description  | Notes
 
 <a name="deletePet"></a>
 # **deletePet**
-> deletePet(petId, apiKey)
+> deletePet(petId, api\_key)
 
 Deletes a pet
 
@@ -50,7 +50,7 @@ Deletes a pet
 Name | Type | Description  | Notes
 ------------- | ------------- | ------------- | -------------
  **petId** | **Long**| Pet id to delete | [default to null]
- **apiKey** | **String**|  | [optional] [default to null]
+ **api\_key** | **String**|  | [optional] [default to null]
 
 ### Return type
 
@@ -148,7 +148,7 @@ Name | Type | Description  | Notes
 
 <a name="updatePet"></a>
 # **updatePet**
-> Pet updatePet(pet)
+> Pet updatePet(Pet)
 
 Update an existing pet
 
@@ -156,7 +156,7 @@ Update an existing pet
 
 Name | Type | Description  | Notes
 ------------- | ------------- | ------------- | -------------
- **pet** | [**Pet**](..//Models/Pet.md)| Pet object that needs to be added to the store |
+ **Pet** | [**Pet**](..//Models/Pet.md)| Pet object that needs to be added to the store |
 
 ### Return type
 

samples/documentation/markdown/Apis/StoreApi.md

@@ -90,7 +90,7 @@ No authorization required
 
 <a name="placeOrder"></a>
 # **placeOrder**
-> Order placeOrder(order)
+> Order placeOrder(Order)
 
 Place an order for a pet
 
@@ -98,7 +98,7 @@ Place an order for a pet
 
 Name | Type | Description  | Notes
 ------------- | ------------- | ------------- | -------------
- **order** | [**Order**](..//Models/Order.md)| order placed for purchasing the pet |
+ **Order** | [**Order**](..//Models/Order.md)| order placed for purchasing the pet |
 
 ### Return type
 

samples/documentation/markdown/Apis/UserApi.md

@@ -16,7 +16,7 @@ Method | HTTP request | Description
 
 <a name="createUser"></a>
 # **createUser**
-> createUser(user)
+> createUser(User)
 
 Create user
 
@@ -26,7 +26,7 @@ Create user
 
 Name | Type | Description  | Notes
 ------------- | ------------- | ------------- | -------------
- **user** | [**User**](..//Models/User.md)| Created user object |
+ **User** | [**User**](..//Models/User.md)| Created user object |
 
 ### Return type
 
@@ -34,7 +34,7 @@ null (empty response body)
 
 ### Authorization
 
-[auth_cookie](../README.md#auth_cookie)
+[api_key](../README.md#api_key)
 
 ### HTTP request headers
 
@@ -43,7 +43,7 @@ null (empty response body)
 
 <a name="createUsersWithArrayInput"></a>
 # **createUsersWithArrayInput**
-> createUsersWithArrayInput(user)
+> createUsersWithArrayInput(User)
 
 Creates list of users with given input array
 
@@ -51,7 +51,7 @@ Creates list of users with given input array
 
 Name | Type | Description  | Notes
 ------------- | ------------- | ------------- | -------------
- **user** | [**List**](..//Models/User.md)| List of user object |
+ **User** | [**List**](..//Models/User.md)| List of user object |
 
 ### Return type
 
@@ -59,7 +59,7 @@ null (empty response body)
 
 ### Authorization
 
-[auth_cookie](../README.md#auth_cookie)
+[api_key](../README.md#api_key)
 
 ### HTTP request headers
 
@@ -68,7 +68,7 @@ null (empty response body)
 
 <a name="createUsersWithListInput"></a>
 # **createUsersWithListInput**
-> createUsersWithListInput(user)
+> createUsersWithListInput(User)
 
 Creates list of users with given input array
 
@@ -76,7 +76,7 @@ Creates list of users with given input array
 
 Name | Type | Description  | Notes
 ------------- | ------------- | ------------- | -------------
- **user** | [**List**](..//Models/User.md)| List of user object |
+ **User** | [**List**](..//Models/User.md)| List of user object |
 
 ### Return type
 
@@ -84,7 +84,7 @@ null (empty response body)
 
 ### Authorization
 
-[auth_cookie](../README.md#auth_cookie)
+[api_key](../README.md#api_key)
 
 ### HTTP request headers
 
@@ -111,7 +111,7 @@ null (empty response body)
 
 ### Authorization
 
-[auth_cookie](../README.md#auth_cookie)
+[api_key](../README.md#api_key)
 
 ### HTTP request headers
 
@@ -184,7 +184,7 @@ null (empty response body)
 
 ### Authorization
 
-[auth_cookie](../README.md#auth_cookie)
+[api_key](../README.md#api_key)
 
 ### HTTP request headers
 
@@ -193,7 +193,7 @@ null (empty response body)
 
 <a name="updateUser"></a>
 # **updateUser**
-> updateUser(username, user)
+> updateUser(username, User)
 
 Updated user
 
@@ -204,7 +204,7 @@ Updated user
 Name | Type | Description  | Notes
 ------------- | ------------- | ------------- | -------------
  **username** | **String**| name that need to be deleted | [default to null]
- **user** | [**User**](..//Models/User.md)| Updated user object |
+ **User** | [**User**](..//Models/User.md)| Updated user object |
 
 ### Return type
 
@@ -212,7 +212,7 @@ null (empty response body)
 
 ### Authorization
 
-[auth_cookie](../README.md#auth_cookie)
+[api_key](../README.md#api_key)
 
 ### HTTP request headers
 

samples/documentation/markdown/README.md

@@ -52,13 +52,6 @@ Class | Method | HTTP request | Description
 - **API key parameter name**: api_key
 - **Location**: HTTP header
 
-<a name="auth_cookie"></a>
-### auth_cookie
-
-- **Type**: API key
-- **API key parameter name**: AUTH_KEY
-- **Location**: 
-
 <a name="petstore_auth"></a>
 ### petstore_auth