forked from loafle/openapi-generator-original
Improves generator docs, adds metadata section (#11262)
* Refactors generator md creation, adds generateMdMetadata * Removes extra space * Adds docs updates * Fixes table definition for metadata * Docs update * Docs update * Updates title, removes sidebar_label because it was not doing anything on pages like https://openapi-generator.tech/docs/generators/android * Docs updated
This commit is contained in:
Justin Black
GitHub
@@ -70,6 +70,9 @@ public class ConfigHelp extends OpenApiGeneratorCommand {
|
||||
@Option(name = {"--import-mappings"}, title = "import mappings", description = "displays the default import mappings (types and aliases, and what imports they will pull into the template)")
|
||||
private Boolean importMappings;
|
||||
|
||||
@Option(name = {"--metadata"}, title = "metadata", description = "displays the generator metadata like the help txt for the generator and generator type etc")
|
||||
private Boolean metadata;
|
||||
|
||||
@Option(name = {"--language-specific-primitive"}, title = "language specific primitives", description = "displays the language specific primitives (types which require no additional imports, or which may conflict with user defined model names)")
|
||||
private Boolean languageSpecificPrimitives;
|
||||
|
||||
@@ -104,6 +107,7 @@ public class ConfigHelp extends OpenApiGeneratorCommand {
|
||||
languageSpecificPrimitives = Boolean.TRUE;
|
||||
importMappings = Boolean.TRUE;
|
||||
featureSets = Boolean.TRUE;
|
||||
metadata = Boolean.TRUE;
|
||||
}
|
||||
|
||||
try {
|
||||
@@ -153,26 +157,8 @@ public class ConfigHelp extends OpenApiGeneratorCommand {
|
||||
}
|
||||
}
|
||||
|
||||
private void generateMarkdownHelp(StringBuilder sb, CodegenConfig config) {
|
||||
if (Boolean.TRUE.equals(markdownHeader)) {
|
||||
sb.append("---").append(newline);
|
||||
sb.append("title: Config Options for ").append(generatorName).append(newline);
|
||||
sb.append("sidebar_label: ").append(generatorName).append(newline);
|
||||
sb.append("---").append(newline);
|
||||
sb.append(newline);
|
||||
sb.append("These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.");
|
||||
sb.append(newline);
|
||||
} else {
|
||||
sb.append(newline);
|
||||
sb.append("## CONFIG OPTIONS");
|
||||
|
||||
if (Boolean.TRUE.equals(namedHeader)) {
|
||||
sb.append(" for <em>").append(generatorName).append("</em>").append(newline);
|
||||
}
|
||||
}
|
||||
|
||||
private void generateMdConfigOptions(StringBuilder sb, CodegenConfig config) {
|
||||
sb.append(newline);
|
||||
|
||||
sb.append("| Option | Description | Values | Default |").append(newline);
|
||||
sb.append("| ------ | ----------- | ------ | ------- |").append(newline);
|
||||
|
||||
@@ -210,90 +196,152 @@ public class ConfigHelp extends OpenApiGeneratorCommand {
|
||||
// default
|
||||
sb.append(escapeHtml4(langCliOption.getDefault())).append("|").append(newline);
|
||||
});
|
||||
}
|
||||
|
||||
private void generateMdImportMappings(StringBuilder sb, CodegenConfig config) {
|
||||
sb.append(newline).append("## IMPORT MAPPING").append(newline).append(newline);
|
||||
|
||||
sb.append("| Type/Alias | Imports |").append(newline);
|
||||
sb.append("| ---------- | ------- |").append(newline);
|
||||
|
||||
config.importMapping()
|
||||
.entrySet()
|
||||
.stream()
|
||||
.sorted(Map.Entry.comparingByKey())
|
||||
.forEachOrdered(kvp -> {
|
||||
sb.append("|").append(escapeHtml4(kvp.getKey())).append("|").append(escapeHtml4(kvp.getValue())).append("|");
|
||||
sb.append(newline);
|
||||
});
|
||||
|
||||
sb.append(newline);
|
||||
}
|
||||
|
||||
private void generateMdInstantiationTypes(StringBuilder sb, CodegenConfig config) {
|
||||
sb.append(newline).append("## INSTANTIATION TYPES").append(newline).append(newline);
|
||||
|
||||
sb.append("| Type/Alias | Instantiated By |").append(newline);
|
||||
sb.append("| ---------- | --------------- |").append(newline);
|
||||
|
||||
config.instantiationTypes()
|
||||
.entrySet()
|
||||
.stream()
|
||||
.sorted(Map.Entry.comparingByKey())
|
||||
.forEachOrdered(kvp -> {
|
||||
sb.append("|").append(escapeHtml4(kvp.getKey())).append("|").append(escapeHtml4(kvp.getValue())).append("|");
|
||||
sb.append(newline);
|
||||
});
|
||||
|
||||
sb.append(newline);
|
||||
}
|
||||
|
||||
private void generateMdLanguageSpecificPrimitives(StringBuilder sb, CodegenConfig config) {
|
||||
sb.append(newline).append("## LANGUAGE PRIMITIVES").append(newline).append(newline);
|
||||
|
||||
sb.append("<ul class=\"column-ul\">").append(newline);
|
||||
config.languageSpecificPrimitives()
|
||||
.stream()
|
||||
.sorted(String::compareTo)
|
||||
.forEach(s -> sb.append("<li>").append(escapeHtml4(s)).append("</li>").append(newline));
|
||||
sb.append("</ul>").append(newline);
|
||||
}
|
||||
|
||||
private void generateMdReservedWords(StringBuilder sb, CodegenConfig config) {
|
||||
sb.append(newline).append("## RESERVED WORDS").append(newline).append(newline);
|
||||
|
||||
sb.append("<ul class=\"column-ul\">").append(newline);
|
||||
config.reservedWords()
|
||||
.stream()
|
||||
.sorted(String::compareTo)
|
||||
.forEach(s -> sb.append("<li>").append(escapeHtml4(s)).append("</li>").append(newline));
|
||||
sb.append("</ul>").append(newline);
|
||||
}
|
||||
|
||||
private void generateMdFeatureSets(StringBuilder sb, CodegenConfig config) {
|
||||
sb.append(newline).append("## FEATURE SET").append(newline).append(newline);
|
||||
|
||||
List<FeatureSet.FeatureSetFlattened> flattened = config.getGeneratorMetadata().getFeatureSet().flatten();
|
||||
flattened.sort(Comparator.comparing(FeatureSet.FeatureSetFlattened::getFeatureCategory));
|
||||
|
||||
AtomicReference<String> lastCategory = new AtomicReference<>();
|
||||
flattened.forEach(featureSet -> {
|
||||
if (!featureSet.getFeatureCategory().equals(lastCategory.get())) {
|
||||
lastCategory.set(featureSet.getFeatureCategory());
|
||||
|
||||
String[] header = StringUtils.splitByCharacterTypeCamelCase(featureSet.getFeatureCategory());
|
||||
sb.append(newline).append("### ").append(StringUtils.join(header, " ")).append(newline);
|
||||
|
||||
sb.append("| Name | Supported | Defined By |").append(newline);
|
||||
sb.append("| ---- | --------- | ---------- |").append(newline);
|
||||
}
|
||||
|
||||
// Appends a ✓ or ✗ for support
|
||||
sb.append("|").append(featureSet.getFeatureName())
|
||||
.append("|").append(featureSet.isSupported() ? "✓" : "✗")
|
||||
.append("|").append(StringUtils.join(featureSet.getSource(), ","))
|
||||
.append(newline);
|
||||
});
|
||||
}
|
||||
|
||||
private void generateMdConfigOptionsHeader(StringBuilder sb, CodegenConfig config) {
|
||||
if (Boolean.TRUE.equals(markdownHeader)) {
|
||||
sb.append("## CONFIG OPTIONS").append(newline);
|
||||
sb.append("These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.");
|
||||
sb.append(newline);
|
||||
} else {
|
||||
sb.append(newline);
|
||||
sb.append("## CONFIG OPTIONS");
|
||||
|
||||
if (Boolean.TRUE.equals(namedHeader)) {
|
||||
sb.append(" for <em>").append(generatorName).append("</em>").append(newline);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private void generateMdMetadata(StringBuilder sb, CodegenConfig config) {
|
||||
sb.append("## METADATA").append(newline).append(newline);
|
||||
|
||||
sb.append("| Property | Value | Notes |").append(newline);
|
||||
sb.append("| -------- | ----- | ----- |").append(newline);
|
||||
sb.append("| generator name | "+config.getName()+" | pass this to the generate command after -g |").append(newline);
|
||||
sb.append("| generator type | "+config.getTag()+" | |").append(newline);
|
||||
sb.append("| helpTxt | "+config.getHelp()+" | |").append(newline);
|
||||
|
||||
sb.append(newline);
|
||||
}
|
||||
|
||||
private void generateMarkdownHelp(StringBuilder sb, CodegenConfig config) {
|
||||
if (Boolean.TRUE.equals(markdownHeader)) {
|
||||
sb.append("---").append(newline);
|
||||
sb.append("title: Documentation for the " + generatorName + " Generator").append(newline);
|
||||
sb.append("---").append(newline);
|
||||
sb.append(newline);
|
||||
}
|
||||
|
||||
if (Boolean.TRUE.equals(metadata)) {
|
||||
generateMdMetadata(sb, config);
|
||||
}
|
||||
|
||||
generateMdConfigOptionsHeader(sb, config);
|
||||
generateMdConfigOptions(sb, config);
|
||||
|
||||
if (Boolean.TRUE.equals(importMappings)) {
|
||||
sb.append(newline).append("## IMPORT MAPPING").append(newline).append(newline);
|
||||
|
||||
sb.append("| Type/Alias | Imports |").append(newline);
|
||||
sb.append("| ---------- | ------- |").append(newline);
|
||||
|
||||
config.importMapping()
|
||||
.entrySet()
|
||||
.stream()
|
||||
.sorted(Map.Entry.comparingByKey())
|
||||
.forEachOrdered(kvp -> {
|
||||
sb.append("|").append(escapeHtml4(kvp.getKey())).append("|").append(escapeHtml4(kvp.getValue())).append("|");
|
||||
sb.append(newline);
|
||||
});
|
||||
|
||||
sb.append(newline);
|
||||
generateMdImportMappings(sb, config);
|
||||
}
|
||||
|
||||
if (Boolean.TRUE.equals(instantiationTypes)) {
|
||||
sb.append(newline).append("## INSTANTIATION TYPES").append(newline).append(newline);
|
||||
|
||||
sb.append("| Type/Alias | Instantiated By |").append(newline);
|
||||
sb.append("| ---------- | --------------- |").append(newline);
|
||||
|
||||
config.instantiationTypes()
|
||||
.entrySet()
|
||||
.stream()
|
||||
.sorted(Map.Entry.comparingByKey())
|
||||
.forEachOrdered(kvp -> {
|
||||
sb.append("|").append(escapeHtml4(kvp.getKey())).append("|").append(escapeHtml4(kvp.getValue())).append("|");
|
||||
sb.append(newline);
|
||||
});
|
||||
|
||||
sb.append(newline);
|
||||
generateMdInstantiationTypes(sb, config);
|
||||
}
|
||||
|
||||
if (Boolean.TRUE.equals(languageSpecificPrimitives)) {
|
||||
sb.append(newline).append("## LANGUAGE PRIMITIVES").append(newline).append(newline);
|
||||
|
||||
sb.append("<ul class=\"column-ul\">").append(newline);
|
||||
config.languageSpecificPrimitives()
|
||||
.stream()
|
||||
.sorted(String::compareTo)
|
||||
.forEach(s -> sb.append("<li>").append(escapeHtml4(s)).append("</li>").append(newline));
|
||||
sb.append("</ul>").append(newline);
|
||||
generateMdLanguageSpecificPrimitives(sb, config);
|
||||
}
|
||||
|
||||
if (Boolean.TRUE.equals(reservedWords)) {
|
||||
sb.append(newline).append("## RESERVED WORDS").append(newline).append(newline);
|
||||
|
||||
sb.append("<ul class=\"column-ul\">").append(newline);
|
||||
config.reservedWords()
|
||||
.stream()
|
||||
.sorted(String::compareTo)
|
||||
.forEach(s -> sb.append("<li>").append(escapeHtml4(s)).append("</li>").append(newline));
|
||||
sb.append("</ul>").append(newline);
|
||||
generateMdReservedWords(sb, config);
|
||||
}
|
||||
|
||||
if (Boolean.TRUE.equals(featureSets)) {
|
||||
sb.append(newline).append("## FEATURE SET").append(newline).append(newline);
|
||||
|
||||
List<FeatureSet.FeatureSetFlattened> flattened = config.getGeneratorMetadata().getFeatureSet().flatten();
|
||||
flattened.sort(Comparator.comparing(FeatureSet.FeatureSetFlattened::getFeatureCategory));
|
||||
|
||||
AtomicReference<String> lastCategory = new AtomicReference<>();
|
||||
flattened.forEach(featureSet -> {
|
||||
if (!featureSet.getFeatureCategory().equals(lastCategory.get())) {
|
||||
lastCategory.set(featureSet.getFeatureCategory());
|
||||
|
||||
String[] header = StringUtils.splitByCharacterTypeCamelCase(featureSet.getFeatureCategory());
|
||||
sb.append(newline).append("### ").append(StringUtils.join(header, " ")).append(newline);
|
||||
|
||||
sb.append("| Name | Supported | Defined By |").append(newline);
|
||||
sb.append("| ---- | --------- | ---------- |").append(newline);
|
||||
}
|
||||
|
||||
// Appends a ✓ or ✗ for support
|
||||
sb.append("|").append(featureSet.getFeatureName())
|
||||
.append("|").append(featureSet.isSupported() ? "✓" : "✗")
|
||||
.append("|").append(StringUtils.join(featureSet.getSource(), ","))
|
||||
.append(newline);
|
||||
});
|
||||
generateMdFeatureSets(sb, config);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user