diff --git a/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/AsciidocDocumentationCodegen.java b/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/AsciidocDocumentationCodegen.java index f8808929a36..db3b11e4267 100644 --- a/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/AsciidocDocumentationCodegen.java +++ b/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); } } diff --git a/modules/openapi-generator/src/main/resources/asciidoc-documentation/index.mustache b/modules/openapi-generator/src/main/resources/asciidoc-documentation/index.mustache index 664cac30920..fcab76298ef 100644 --- a/modules/openapi-generator/src/main/resources/asciidoc-documentation/index.mustache +++ b/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 diff --git a/modules/openapi-generator/src/main/resources/asciidoc-documentation/params.mustache b/modules/openapi-generator/src/main/resources/asciidoc-documentation/params.mustache index 029f10fb5a5..7307bf155e8 100644 --- a/modules/openapi-generator/src/main/resources/asciidoc-documentation/params.mustache +++ b/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 diff --git a/samples/documentation/asciidoc/index.adoc b/samples/documentation/asciidoc/index.adoc index 5b8e07a5705..bc9f84fa1f2 100644 --- a/samples/documentation/asciidoc/index.adoc +++ b/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"] |===