From 828bdebdac9a0c24df3003810861a2693128f32e Mon Sep 17 00:00:00 2001 From: Tetiana Servirog <64489476+TetianaServirog@users.noreply.github.com> Date: Sun, 2 Aug 2020 00:21:18 +0300 Subject: [PATCH] [MARKDOWN] Fix issue 6089 with property and parameter names (#6105) Co-authored-by: Jim Schubert --- .../MarkdownDocumentationCodegen.java | 52 +++++++++++++++---- .../markdown/.openapi-generator/FILES | 12 +++++ samples/documentation/markdown/Apis/PetApi.md | 12 ++--- .../documentation/markdown/Apis/StoreApi.md | 4 +- .../documentation/markdown/Apis/UserApi.md | 28 +++++----- samples/documentation/markdown/README.md | 7 --- 6 files changed, 75 insertions(+), 40 deletions(-) create mode 100644 samples/documentation/markdown/.openapi-generator/FILES diff --git a/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/MarkdownDocumentationCodegen.java b/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/MarkdownDocumentationCodegen.java index d0985397042..1d76b22cbda 100644 --- a/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/MarkdownDocumentationCodegen.java +++ b/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 io.swagger.models.properties.ArrayProperty; -import io.swagger.models.properties.MapProperty; -import io.swagger.models.properties.Property; -import io.swagger.models.parameters.Parameter; - -import java.io.File; -import java.util.*; - -import org.apache.commons.lang3.StringUtils; - +import org.openapitools.codegen.CodegenConfig; +import org.openapitools.codegen.CodegenType; +import org.openapitools.codegen.DefaultCodegen; +import org.openapitools.codegen.SupportingFile; 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; + } } diff --git a/samples/documentation/markdown/.openapi-generator/FILES b/samples/documentation/markdown/.openapi-generator/FILES new file mode 100644 index 00000000000..53bf49ac0cf --- /dev/null +++ b/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 diff --git a/samples/documentation/markdown/Apis/PetApi.md b/samples/documentation/markdown/Apis/PetApi.md index 18e6055274f..956077f32ee 100644 --- a/samples/documentation/markdown/Apis/PetApi.md +++ b/samples/documentation/markdown/Apis/PetApi.md @@ -16,7 +16,7 @@ Method | HTTP request | Description # **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 # **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 # **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 diff --git a/samples/documentation/markdown/Apis/StoreApi.md b/samples/documentation/markdown/Apis/StoreApi.md index b6d71962894..9c1dd2b588e 100644 --- a/samples/documentation/markdown/Apis/StoreApi.md +++ b/samples/documentation/markdown/Apis/StoreApi.md @@ -90,7 +90,7 @@ No authorization required # **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 diff --git a/samples/documentation/markdown/Apis/UserApi.md b/samples/documentation/markdown/Apis/UserApi.md index 071091c7416..01aaf35f4f4 100644 --- a/samples/documentation/markdown/Apis/UserApi.md +++ b/samples/documentation/markdown/Apis/UserApi.md @@ -16,7 +16,7 @@ Method | HTTP request | Description # **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) # **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) # **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) # **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 diff --git a/samples/documentation/markdown/README.md b/samples/documentation/markdown/README.md index 0ceb7bae32d..b40f7e919cd 100644 --- a/samples/documentation/markdown/README.md +++ b/samples/documentation/markdown/README.md @@ -52,13 +52,6 @@ Class | Method | HTTP request | Description - **API key parameter name**: api_key - **Location**: HTTP header - -### auth_cookie - -- **Type**: API key -- **API key parameter name**: AUTH_KEY -- **Location**: - ### petstore_auth