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
This commit is contained in:
Jens Reimann 2020-06-15 03:29:26 +02:00 committed by GitHub
parent 6f5ec7deef
commit 171337e5f3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 113 additions and 16 deletions

View File

@ -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);
}
}

View File

@ -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

View File

@ -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

View File

@ -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"]
|===