Add some AsciiDoc tweaks (#6436)

* Fix a section level issue in the parameters section
* 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

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)) {
+    private void processBooleanFlag(String flag, boolean value) {
-            this.setHeaderAttributes(convertPropertyToBooleanAndWriteBack(HEADER_ATTRIBUTES_FLAG));
+        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

@@ -1,9 +1,14 @@
 ===== 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"]
 |===