[BUG][MARKDOWN] Parameter and property names are needlessly changed according to default specialCharReplacements mapping
Created by: TanyaS
Bug Report Checklist
-
Have you provided a full/minimal spec to reproduce the issue? -
Have you validated the input using an OpenAPI validator (example)? -
What's the version of OpenAPI Generator used? -
Have you search for related issues/PRs? -
What's the actual output vs expected output? -
[Optional] Bounty to sponsor the fix (example)
Description
Different languages have different set of acceptable symbols for identifiers.
However, MarkdownDocumentationCodegen doesn't override specialCharReplacements mapping, DefaultCodegen#toParamName and DefaultCodegen#toVarName methods. This leads to parameter and variable names being processed according to default logic, for example:
"components": {
"schemas": {
"Pet": {
"type": "object",
"properties": {
"_name_ext_": {
"type": "string"
}
becomes
Name | Type | Description | Notes |
---|---|---|---|
UnderscorenameUnderscoreextUnderscore | String | [optional] [default to null] |
openapi-generator version
4.3.1-SNAPSHOT
OpenAPI declaration file content or url
https://gist.github.com/TanyaS/d7067e018b42355695574d7f0e90512b
Command line used for generation
generate \
-g markdown \
-o markdown \
-i openapi-spec-with-wierd-names.json \
--language-specific-primitives string
Steps to reproduce
Generate markdown docs using provided spec and cli command.
Related issues/PRs
Suggest a fix
specialCharReplacements
mapping can be overridden like so:
@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. It 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("|", "\\|");
}
And toParamName
method can be overridden to omit camelization:
/**
* 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;
}