Add some AsciiDoc tweaks

Created by: ctron

• Allow to use an introduction section instead of abstract
• Allow to use table titles rather than wrapping with sections
• Allow to use HTTP method and path as operation title
• Allow to skip examples sections

PR checklist

• Read the contribution guidelines.
• If contributing template-only or documentation-only changes which will change sample output, build the project before.
• Run the shell script(s) under ./bin/ (or Windows batch scripts under.\bin\windows) to update Petstore samples related to your fix. This is important, as CI jobs will verify all generator outputs of your HEAD commit, and these must match the expectations made by your contribution. You only need to run ./bin/{LANG}-petstore.sh, ./bin/openapi3/{LANG}-petstore.sh if updating the code or mustache templates for a language ({LANG}) (e.g. php, ruby, python, etc).
• File the PR against the correct branch: master, 4.3.x, 5.0.x. Default: master.
• Copy the technical committee to review the pull request if your PR is targeting a particular programming language.

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

@@ -49,6 +49,10 @@ public class AsciidocDocumentationCodegen extends DefaultCodegen implements Code
     public static final String SPEC_DIR = "specDir";
     public static final String SNIPPET_DIR = "snippetDir";
     public static final String HEADER_ATTRIBUTES_FLAG = "headerAttributes";
+    public static final String USE_INTRODUCTION_FLAG = "useIntroduction";
+    public static final String SKIP_EXAMPLES_FLAG = "skipExamples";
+    public static final String USE_METHOD_AND_PATH_FLAG = "useMethodAndPath";
+    public static final String USE_TABLE_TITLES_FLAG = "useTableTitles";
 
     /**
      * Lambda emitting an asciidoc "include::filename.adoc[]" if file is found in
@@ -150,6 +154,10 @@ public class AsciidocDocumentationCodegen extends DefaultCodegen implements Code
     protected String artifactId = "openapi-client";
     protected String artifactVersion = "1.0.0";
     protected boolean headerAttributes = true;
+    protected boolean useIntroduction = false;
+    protected boolean skipExamples = false;
+    protected boolean useMethodAndPath = false;
+    protected boolean useTableTitles = false;
 
     private IncludeMarkupLambda includeSpecMarkupLambda;
     private IncludeMarkupLambda includeSnippetMarkupLambda;
@@ -228,6 +236,18 @@ public class AsciidocDocumentationCodegen extends DefaultCodegen implements Code
         cliOptions.add(CliOption.newBoolean(HEADER_ATTRIBUTES_FLAG,
                 "generation of asciidoc header meta data attributes (set to false to suppress, default: true)",
                 true));
+        cliOptions.add(CliOption.newBoolean(USE_INTRODUCTION_FLAG,
+                "use introduction section, rather than an initial abstract (default: false)",
+                false));
+        cliOptions.add(CliOption.newBoolean(SKIP_EXAMPLES_FLAG,
+                "skip examples sections (default: false)",
+                false));
+        cliOptions.add(CliOption.newBoolean(USE_METHOD_AND_PATH_FLAG,
+                "Use HTTP method and path as operation heading, instead of operation id (default: false)",
+                false));
+        cliOptions.add(CliOption.newBoolean(USE_TABLE_TITLES_FLAG,
+                "Use titles for tables, rather than wrapping tables instead their own section (default: false)",
+                false));
 
         additionalProperties.put("appName", "OpenAPI Sample description");
         additionalProperties.put("appDescription", "A sample OpenAPI documentation");
@@ -266,6 +286,38 @@ public class AsciidocDocumentationCodegen extends DefaultCodegen implements Code
         this.headerAttributes = headerAttributes;
     }
 
+    public boolean isUseIntroduction() {
+        return useIntroduction;
+    }
+
+    public void setUseIntroduction(boolean useIntroduction) {
+        this.useIntroduction = useIntroduction;
+    }
+
+    public boolean isSkipExamples() {
+        return skipExamples;
+    }
+
+    public void setSkipExamples(boolean skipExamples) {
+        this.skipExamples = skipExamples;
+    }
+
+    public boolean isUseMethodAndPath() {
+        return useMethodAndPath;
+    }
+
+    public void setUseMethodAndPath(boolean useMethodAndPath) {
+        this.useMethodAndPath = useMethodAndPath;
+    }
+
+    public boolean isUseTableTitles() {
+        return useTableTitles;
+    }
+
+    public void setUseTableTitles(boolean useTableTitles) {
+        this.useTableTitles = useTableTitles;
+    }
+
     @Override
     public void processOpts() {
         super.processOpts();
@@ -291,11 +343,18 @@ public class AsciidocDocumentationCodegen extends DefaultCodegen implements Code
         this.linkSnippetMarkupLambda = new LinkMarkupLambda(snippetDir);
         additionalProperties.put("snippetlink", this.linkSnippetMarkupLambda);
 
+        processBooleanFlag(HEADER_ATTRIBUTES_FLAG, headerAttributes);
+        processBooleanFlag(USE_INTRODUCTION_FLAG, useIntroduction);
+        processBooleanFlag(SKIP_EXAMPLES_FLAG, skipExamples);
+        processBooleanFlag(USE_METHOD_AND_PATH_FLAG, useMethodAndPath);
+        processBooleanFlag(USE_TABLE_TITLES_FLAG, useTableTitles);
+    }
 
-        if (additionalProperties.containsKey(HEADER_ATTRIBUTES_FLAG)) {
-            this.setHeaderAttributes(convertPropertyToBooleanAndWriteBack(HEADER_ATTRIBUTES_FLAG));
+    private void processBooleanFlag(String flag, boolean value) {
+        if (additionalProperties.containsKey(flag)) {
+            this.setHeaderAttributes(convertPropertyToBooleanAndWriteBack(flag));
         } else {
-            additionalProperties.put(HEADER_ATTRIBUTES_FLAG, headerAttributes);
+            additionalProperties.put(flag, value);
         }
     }
 

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

@@ -14,8 +14,13 @@
 :app-name: {{appName}}
 {{/headerAttributes}}
 
+{{#useIntroduction}}
+== Introduction
+{{/useIntroduction}}
+{{^useIntroduction}}
 [abstract]
 .Abstract
+{{/useIntroduction}}
 {{{appDescription}}}
 
 {{#specinclude}}intro.adoc{{/specinclude}}
@@ -46,9 +51,17 @@
 {{#operation}}
 
 [.{{nickname}}]
+{{#useMethodAndPath}}
+==== {{httpMethod}} {{path}}
+
+Operation Id:: {{nickname}}
+
+{{/useMethodAndPath}}
+{{^useMethodAndPath}}
 ==== {{nickname}}
     
 `{{httpMethod}} {{path}}`
+{{/useMethodAndPath}}
 
 {{{summary}}}
 
@@ -96,12 +109,14 @@
 {{/responses}}
 |===         
 
+{{^skipExamples}}
 ===== Samples
 
 {{#snippetinclude}}{{path}}/{{httpMethod}}/http-request.adoc{{/snippetinclude}}
 {{#snippetinclude}}{{path}}/{{httpMethod}}/http-response.adoc{{/snippetinclude}}
 
 {{#snippetlink}}* wiremock data, {{path}}/{{httpMethod}}/{{httpMethod}}.json{{/snippetlink}}
+{{/skipExamples}}
 
 ifdef::internal-generation[]
 ===== Implementation

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

 ===== Parameters
 
 {{#hasPathParams}}
+{{^useTableTitles}}
 ====== Path Parameters
+{{/useTableTitles}}
 
 [cols="2,3,1,1,1"]
+{{#useTableTitles}}
+.Path Parameters
+{{/useTableTitles}}
 |===         
 |Name| Description| Required| Default| Pattern
 
@@ -14,9 +19,14 @@
 {{/hasPathParams}}
 
 {{#hasBodyParam}}
-===== Body Parameter
+{{^useTableTitles}}
+====== Body Parameter
+{{/useTableTitles}}
 
 [cols="2,3,1,1,1"]
+{{#useTableTitles}}
+.Body Parameter
+{{/useTableTitles}}
 |===         
 |Name| Description| Required| Default| Pattern
 
@@ -27,9 +37,14 @@
 {{/hasBodyParam}}
 
 {{#hasFormParams}}
-===== Form Parameter
+{{^useTableTitles}}
+====== Form Parameters
+{{/useTableTitles}}
 
 [cols="2,3,1,1,1"]
+{{#useTableTitles}}
+.Form Parameters
+{{/useTableTitles}}
 |===         
 |Name| Description| Required| Default| Pattern
 
@@ -40,9 +55,14 @@
 {{/hasFormParams}}
 
 {{#hasHeaderParams}}
+{{^useTableTitles}}
 ====== Header Parameters
+{{/useTableTitles}}
 
 [cols="2,3,1,1,1"]
+{{#useTableTitles}}
+.Header Parameters
+{{/useTableTitles}}
 |===         
 |Name| Description| Required| Default| Pattern
 
@@ -53,9 +73,14 @@
 {{/hasHeaderParams}}
 
 {{#hasQueryParams}}
+{{^useTableTitles}}
 ====== Query Parameters
+{{/useTableTitles}}
 
 [cols="2,3,1,1,1"]
+{{#useTableTitles}}
+.Query Parameters
+{{/useTableTitles}}
 |===         
 |Name| Description| Required| Default| Pattern
 

samples/documentation/asciidoc/index.adoc

@@ -24,8 +24,6 @@ This is a sample server Petstore server. For this sample, you can use the api ke
 
 
 * *APIKey* KeyParamName:     _api_key_,     KeyInQuery: _false_, KeyInHeader: _true_
-
-* *APIKey* KeyParamName:     _AUTH_KEY_,     KeyInQuery: _false_, KeyInHeader: _false_
 * *OAuth*  AuthorizationUrl: _http://petstore.swagger.io/api/oauth/dialog_, TokenUrl:   __ 
 
 
@@ -56,7 +54,7 @@ Add a new pet to the store
 ===== Parameters
 
 
-===== Body Parameter
+====== Body Parameter
 
 [cols="2,3,1,1,1"]
 |===         
@@ -506,7 +504,7 @@ Update an existing pet
 ===== Parameters
 
 
-===== Body Parameter
+====== Body Parameter
 
 [cols="2,3,1,1,1"]
 |===         
@@ -618,7 +616,7 @@ Updates a pet in the store with form data
 |===         
 
 
-===== Form Parameter
+====== Form Parameters
 
 [cols="2,3,1,1,1"]
 |===         
@@ -717,7 +715,7 @@ uploads an image
 |===         
 
 
-===== Form Parameter
+====== Form Parameters
 
 [cols="2,3,1,1,1"]
 |===         
@@ -1056,7 +1054,7 @@ Place an order for a pet
 ===== Parameters
 
 
-===== Body Parameter
+====== Body Parameter
 
 [cols="2,3,1,1,1"]
 |===         
@@ -1148,7 +1146,7 @@ This can only be done by the logged in user.
 ===== Parameters
 
 
-===== Body Parameter
+====== Body Parameter
 
 [cols="2,3,1,1,1"]
 |===         
@@ -1228,7 +1226,7 @@ Creates list of users with given input array
 ===== Parameters
 
 
-===== Body Parameter
+====== Body Parameter
 
 [cols="2,3,1,1,1"]
 |===         
@@ -1308,7 +1306,7 @@ Creates list of users with given input array
 ===== Parameters
 
 
-===== Body Parameter
+====== Body Parameter
 
 [cols="2,3,1,1,1"]
 |===         
@@ -1741,7 +1739,7 @@ This can only be done by the logged in user.
 
 |===         
 
-===== Body Parameter
+====== Body Parameter
 
 [cols="2,3,1,1,1"]
 |===