[asciidoc] fix names of parameters (#4440)

Fixes #4408 

* fix header hierarchy in model section
* small fix markup on dataformat enum (italic)
* fixes parameter names casing

Author: man-at-home

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

@@ -81,10 +81,10 @@ public void execute(final Template.Fragment frag, final Writer out) throws IOExc
             if (Files.isRegularFile(filePathToInclude)) {
                 LOGGER.debug(
                         "including " + ++includeCount + ". file into markup from: " + filePathToInclude.toString());
-                out.write("\ninclude::" + relativeFileName + "[]\n");
+                out.write("\ninclude::" + relativeFileName + "[opts=optional]\n");
             } else {
                 LOGGER.debug(++notFoundCount + ". file not found, skip include for: " + filePathToInclude.toString());
-                out.write("\n// markup not found, no include ::" + relativeFileName + "[]\n");
+                out.write("\n// markup not found, no include ::" + relativeFileName + "[opts=optional]\n");
             }
         }
     }
@@ -158,6 +158,8 @@ public CodegenType getTag() {
      */
     static String sanitize(final String name) {
         String sanitized = name == null ? "" : name.trim();
+        sanitized = sanitized.replace("//", "/"); // rest paths may or may not end with slashes, leading to redundant
+                                                  // path separators.
         return sanitized.startsWith(File.separator) || sanitized.startsWith("/") ? sanitized.substring(1) : sanitized;
     }
 
@@ -200,10 +202,10 @@ public AsciidocDocumentationCodegen() {
 
         cliOptions.add(new CliOption(SNIPPET_DIR,
                 "path with includable markup snippets (e.g. test output generated by restdoc, default: .")
-                .defaultValue("."));
+                        .defaultValue("."));
         cliOptions.add(new CliOption(SPEC_DIR,
                 "path with includable markup spec files (e.g. handwritten additional docs, default: .")
-                .defaultValue(".."));
+                        .defaultValue(".."));
 
         additionalProperties.put("appName", "OpenAPI Sample description");
         additionalProperties.put("appDescription", "A sample OpenAPI documentation");

modules/openapi-generator/src/main/resources/asciidoc-documentation/index.mustache

@@ -8,7 +8,7 @@
 :keywords: openapi, rest, {{appName}} 
 :specDir: {{specDir}}
 :snippetDir: {{snippetDir}}
-:generator-template: v1 2019-09-03
+:generator-template: v1 2019-11-10
 :info-url: {{infoUrl}}
 :app-name: {{appName}}
 

modules/openapi-generator/src/main/resources/asciidoc-documentation/model.mustache

@@ -5,7 +5,7 @@
     {{#model}}
 
 [#{{classname}}]
-==== _{{classname}}_ {{title}}
+=== _{{classname}}_ {{title}}
 
 {{unescapedDescription}}
 
@@ -15,11 +15,11 @@
 | Field Name| Required| Type| Description| Format
 
 {{#vars}}
-| {{name}} 
+| {{baseName}} 
 | {{#required}}X{{/required}} 
 | {{dataType}} {{#isContainer}} of <<{{complexType}}>>{{/isContainer}} 
 | {{description}}
-| {{{dataFormat}}} {{#isEnum}}Enum: _ {{#_enum}}{{this}}, {{/_enum}}{{/isEnum}} _
+| {{{dataFormat}}} {{#isEnum}}_Enum:_ {{#_enum}}{{this}}, {{/_enum}}{{/isEnum}}
 
 {{/vars}}
 |===

modules/openapi-generator/src/main/resources/asciidoc-documentation/param.mustache

@@ -1,4 +1,4 @@
-| {{paramName}} 
+| {{baseName}} 
 | {{description}} {{#baseType}}<<{{baseType}}>>{{/baseType}} 
 | {{^required}}-{{/required}}{{#required}}X{{/required}} 
 | {{defaultValue}} 

modules/openapi-generator/src/test/java/org/openapitools/codegen/asciidoc/AsciidocSampleGeneratorTest.java

@@ -12,23 +12,25 @@
 import org.openapitools.codegen.config.CodegenConfigurator;
 import org.openapitools.codegen.languages.AsciidocDocumentationCodegen;
 import org.testng.Assert;
+import org.testng.annotations.AfterClass;
+import org.testng.annotations.BeforeClass;
 import org.testng.annotations.Test;
 
+/** several asciidoc content checks with sample openapi v3. */
 public class AsciidocSampleGeneratorTest {
 
-    /** 
-     * ensure api-docs.json includes sample and spec files into markup.
-     * @throws Exception generic exception
-     */
-    @Test
-    public void testSampleAsciidocMarkupGenerationFromJsonWithSpecsAndSamples() throws Exception {
+    public String markupContent = null;
+    public String markupFileName = null;
 
-        File outputTempDirectory = Files.createTempDirectory("test-asciidoc-sample-generator.").toFile();
+    File specDir = new File("src/test/resources/3_0/asciidoc/specs/");
+    File snippetDir = new File("src/test/resources/3_0/asciidoc/generated-snippets/");
 
-        File specDir = new File("src/test/resources/3_0/asciidoc/specs/");
-        File snippetDir = new File("src/test/resources/3_0/asciidoc/generated-snippets/");
+    @BeforeClass
+    public void beforeClassGenerateTestMarkup() throws Exception {
 
-        Assert.assertTrue(specDir.exists(), "test cancel, not specdDir found to use." + specDir.getPath());
+        File outputTempDirectory = Files.createTempDirectory("test-asciidoc-sample-generator.").toFile();
+
+        Assert.assertTrue(specDir.exists(), "test cancel, not specDir found to use." + specDir.getPath());
         Assert.assertTrue(snippetDir.exists(), "test cancel, not snippedDir found to use." + snippetDir.getPath());
 
         final CodegenConfigurator configurator = new CodegenConfigurator().setGeneratorName("asciidoc")
@@ -40,46 +42,77 @@ public void testSampleAsciidocMarkupGenerationFromJsonWithSpecsAndSamples() thro
         DefaultGenerator generator = new DefaultGenerator();
         List<File> files = generator.opts(configurator.toClientOptInput()).generate();
 
-        boolean markupFileGenerated = false;
-
         for (File file : files) {
             if (file.getName().equals("index.adoc")) {
-                markupFileGenerated = true;
-                String markupContent = FileUtils.readFileToString(file, StandardCharsets.UTF_8);
+                this.markupFileName = file.getAbsoluteFile().toString();
+                this.markupContent = FileUtils.readFileToString(file, StandardCharsets.UTF_8);
+            }
+        }
+    }
 
-                // include correct values from cli.
-                Assert.assertTrue(markupContent.contains(":specDir: " + specDir.toString()),
-                        "expected :specDir: in: " + markupContent.substring(0, 350));
-                Assert.assertTrue(markupContent.contains(":snippetDir: " + snippetDir.toString()),
-                        "expected :snippetDir: in: " + markupContent.substring(0, 350));
+    @AfterClass
+    public void afterClassCleanUpTestMarkup() throws Exception {
+        if (this.markupFileName != null) {
+            Files.deleteIfExists(Paths.get(this.markupFileName));
+        }
+    }
 
-                // include correct markup from separate directories, relative links
-                Assert.assertTrue(markupContent.contains("include::rest/project/GET/spec.adoc[]"),
-                        "expected project spec.adoc to be included in " + file.getAbsolutePath());
+    @Test
+    public void testMarkupExistence() {
+        Assert.assertNotNull(this.markupContent, "asciidoc content index.adoc not created.");
+    }
 
-                Assert.assertTrue(markupContent.contains("include::rest/project/GET/implementation.adoc[]"),
-                        "expected project implementation.adoc to be included in " + file.getAbsolutePath());
+    /**
+     * ensure api-docs.json includes sample and spec files directory as attributes.
+     */
+    @Test
+    public void testSampleAsciidocMarkupGenerationFromJsonWithAttributes() throws Exception {
+        Assert.assertTrue(markupContent.contains(":specDir: " + specDir.toString()),
+                "expected :specDir: in: " + markupContent.substring(0, 350));
+        Assert.assertTrue(markupContent.contains(":snippetDir: " + snippetDir.toString()),
+                "expected :snippetDir: in: " + markupContent.substring(0, 350));
+    }
+
+    /**
+     * ensure api-docs.json includes sample and spec files into markup.
+     */
+    @Test
+    public void testSampleAsciidocMarkupGenerationFromJsonWithIncludes() throws Exception {
 
-                Assert.assertTrue(markupContent.contains("include::rest/project/GET/http-request.adoc[]"),
-                        "expected project http-request.adoc to be included in " + file.getAbsolutePath());
+        // include correct markup from separate directories, relative links
+        Assert.assertTrue(markupContent.contains("include::rest/project/GET/spec.adoc["),
+                "expected project spec.adoc to be included in " + markupFileName);
 
-                Assert.assertTrue(markupContent.contains("include::rest/project/GET/http-response.adoc[]"),
-                        "expected project http-response.adoc to be included in " + file.getAbsolutePath());
+        Assert.assertTrue(markupContent.contains("include::rest/project/GET/implementation.adoc["),
+                "expected project implementation.adoc to be included in " + markupFileName);
 
-                Assert.assertTrue(markupContent.contains("link:rest/project/GET/GET.json["),
-                        "expected link: not found in file: " + file.getAbsoluteFile());
+        Assert.assertTrue(markupContent.contains("include::rest/project/GET/http-request.adoc["),
+                "expected project http-request.adoc to be included in " + markupFileName);
 
-                // extract correct value from json
-                Assert.assertTrue(markupContent.contains("= time@work rest api"),
-                        "missing main header for api spec from json: " + markupContent.substring(0, 100));
-            }
-            Files.deleteIfExists(Paths.get(file.getAbsolutePath()));
-        }
+        Assert.assertTrue(markupContent.contains("include::rest/project/GET/http-response.adoc["),
+                "expected project http-response.adoc to be included in " + markupFileName);
 
-        Assert.assertTrue(markupFileGenerated, "index.adoc is not generated!");
+        Assert.assertTrue(markupContent.contains("link:rest/project/GET/GET.json["),
+                "expected link: not found in file: " + markupFileName);
+    }
 
-        Files.deleteIfExists(Paths.get(outputTempDirectory.getAbsolutePath(), ".openapi-generator"));
-        Files.deleteIfExists(Paths.get(outputTempDirectory.getAbsolutePath()));
+    /**
+     * markup doc header content.
+     */
+    @Test
+    public void testSampleAsciidocMarkupGenerationFromJsonWithContent() throws Exception {
+        Assert.assertTrue(markupContent.contains("= time@work rest api"),
+                "missing main header for api spec from json: " + markupContent.substring(0, 100));
+
+    }
+
+    /**
+     * fix: parameter name unchanged.
+     */
+    @Test
+    public void testSampleAsciidocMarkupGenerationParameterNameUnchanged() throws Exception {
+        Assert.assertTrue(markupContent.contains("from-iso-date-string"),
+                "keep parameter name from-iso-date-string unchanged.");
     }
 
 }

modules/openapi-generator/src/test/java/org/openapitools/codegen/asciidoc/IncludeMarkupFilterTest.java

@@ -26,7 +26,7 @@ public void testIncludeMarkupFilterDoesNotIncludeMissingFile() {
         final Map<String, Object> ctx = context("specinclude", generator.new IncludeMarkupLambda("DOES_NOT_EXIST"));
 
         final String result = execute("{{#specinclude}}not.an.existing.file.adoc{{/specinclude}}", ctx);
-        Assert.assertTrue(result.contains("// markup not found, no include ::not.an.existing.file.adoc[]"),
+        Assert.assertTrue(result.contains("// markup not found, no include ::not.an.existing.file.adoc["),
                 "unexpected filtered " + result);
     }
 

modules/openapi-generator/src/test/resources/3_0/asciidoc/api-docs.json

@@ -1 +1 @@
-4.1.3-SNAPSHOT
+4.2.1-SNAPSHOT