Skip to content

Commit d04b764

Browse files
kenjones-ciscowing328
kenjones-cisco
authored and
wing328
committed
Feature: Adds doc generation (#6570)
Reference #2359
1 parent 2c7dcbe commit d04b764

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+1815
-31
lines changed

‎modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/BashClientCodegen.java

Lines changed: 112 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,8 @@ public class BashClientCodegen extends DefaultCodegen implements CodegenConfig {
3939
protected String hostEnvironmentVariable;
4040
protected String basicAuthEnvironmentVariable;
4141
protected String apiKeyAuthEnvironmentVariable;
42-
42+
protected String apiDocPath = "docs/";
43+
protected String modelDocPath = "docs/";
4344

4445
public static final String CURL_OPTIONS = "curlOptions";
4546
public static final String PROCESS_MARKDOWN = "processMarkdown";
@@ -105,6 +106,13 @@ public BashClientCodegen() {
105106
apiTemplateFiles.clear();
106107

107108

109+
/**
110+
* docs files.
111+
*/
112+
modelDocTemplateFiles.put("model_doc.mustache", ".md");
113+
apiDocTemplateFiles.put("api_doc.mustache", ".md");
114+
115+
108116
/**
109117
* Templates location for client script and bash completion template.
110118
*/
@@ -169,6 +177,7 @@ public BashClientCodegen() {
169177
typeMapping.put("int", "integer");
170178
typeMapping.put("float", "float");
171179
typeMapping.put("number", "integer");
180+
typeMapping.put("date", "string");
172181
typeMapping.put("DateTime", "string");
173182
typeMapping.put("long", "integer");
174183
typeMapping.put("short", "integer");
@@ -185,12 +194,22 @@ public BashClientCodegen() {
185194
* are available in models, apis, and supporting files.
186195
*/
187196
additionalProperties.put("apiVersion", apiVersion);
197+
// make api and model doc path available in mustache template
198+
additionalProperties.put("apiDocPath", apiDocPath);
199+
additionalProperties.put("modelDocPath", modelDocPath);
188200

189201
/**
190202
* Language Specific Primitives. These types will not trigger imports by
191203
* the client generator
192204
*/
193-
languageSpecificPrimitives = new HashSet<String>();
205+
languageSpecificPrimitives.clear();
206+
languageSpecificPrimitives.add("array");
207+
languageSpecificPrimitives.add("map");
208+
languageSpecificPrimitives.add("boolean");
209+
languageSpecificPrimitives.add("integer");
210+
languageSpecificPrimitives.add("float");
211+
languageSpecificPrimitives.add("string");
212+
languageSpecificPrimitives.add("binary");
194213
}
195214

196215

@@ -239,15 +258,15 @@ public void processOpts() {
239258
}
240259

241260
supportingFiles.add(new SupportingFile(
242-
"client.mustache", "", scriptName));
261+
"client.mustache", "", scriptName));
243262
supportingFiles.add(new SupportingFile(
244-
"bash-completion.mustache", "", scriptName+".bash-completion"));
263+
"bash-completion.mustache", "", scriptName+".bash-completion"));
245264
supportingFiles.add(new SupportingFile(
246-
"zsh-completion.mustache", "", "_"+scriptName));
265+
"zsh-completion.mustache", "", "_"+scriptName));
247266
supportingFiles.add(new SupportingFile(
248-
"README.mustache", "", "README.md"));
267+
"README.mustache", "", "README.md"));
249268
supportingFiles.add(new SupportingFile(
250-
"Dockerfile.mustache", "", "Dockerfile"));
269+
"Dockerfile.mustache", "", "Dockerfile"));
251270
}
252271

253272
public void setCurlOptions(String curlOptions) {
@@ -314,6 +333,25 @@ public String apiFileFolder() {
314333
return outputFolder;
315334
}
316335

336+
@Override
337+
public String apiDocFileFolder() {
338+
return (outputFolder + "/" + apiDocPath);
339+
}
340+
341+
@Override
342+
public String modelDocFileFolder() {
343+
return (outputFolder + "/" + modelDocPath);
344+
}
345+
346+
@Override
347+
public String toModelDocFilename(String name) {
348+
return toModelName(name);
349+
}
350+
351+
@Override
352+
public String toApiDocFilename(String name) {
353+
return toApiName(name);
354+
}
317355

318356
/**
319357
* Optional - type declaration. This is a String which is used by the
@@ -355,8 +393,9 @@ public String getSwaggerType(Property p) {
355393
if(languageSpecificPrimitives.contains(type))
356394
return type;
357395
}
358-
else
396+
else {
359397
type = swaggerType;
398+
}
360399
return toModelName(type);
361400
}
362401

@@ -656,4 +695,69 @@ public void preprocessSwagger(Swagger swagger) {
656695

657696
}
658697

698+
@Override
699+
public void setParameterExampleValue(CodegenParameter p) {
700+
String example;
701+
702+
if (p.defaultValue == null) {
703+
example = p.example;
704+
} else {
705+
example = p.defaultValue;
706+
}
707+
708+
String type = p.baseType;
709+
if (type == null) {
710+
type = p.dataType;
711+
}
712+
713+
if ("string".equalsIgnoreCase(type)) {
714+
if (example == null) {
715+
example = p.paramName + "_example";
716+
}
717+
example = "'" + escapeText(example) + "'";
718+
} else if ("integer".equals(type)) {
719+
if (example == null) {
720+
example = "56";
721+
}
722+
} else if ("float".equalsIgnoreCase(type)) {
723+
if (example == null) {
724+
example = "3.4";
725+
}
726+
} else if ("boolean".equalsIgnoreCase(type)) {
727+
if (example == null) {
728+
example = "True";
729+
}
730+
} else if ("file".equalsIgnoreCase(type)) {
731+
if (example == null) {
732+
example = "/path/to/file";
733+
}
734+
example = "'" + escapeText(example) + "'";
735+
} else if ("date".equalsIgnoreCase(type)) {
736+
if (example == null) {
737+
example = "2013-10-20";
738+
}
739+
example = "'" + escapeText(example) + "'";
740+
} else if ("datetime".equalsIgnoreCase(type)) {
741+
if (example == null) {
742+
example = "2013-10-20T19:20:30+01:00";
743+
}
744+
example = "'" + escapeText(example) + "'";
745+
} else if (!languageSpecificPrimitives.contains(type)) {
746+
// type is a model class, e.g. User
747+
example = type;
748+
} else {
749+
LOGGER.warn("Type " + type + " not handled properly in setParameterExampleValue");
750+
}
751+
752+
if (example == null) {
753+
example = "NULL";
754+
} else if (Boolean.TRUE.equals(p.isListContainer)) {
755+
example = "[" + example + "]";
756+
} else if (Boolean.TRUE.equals(p.isMapContainer)) {
757+
example = "{'key': " + example + "}";
758+
}
759+
760+
p.example = example;
761+
}
762+
659763
}

‎modules/swagger-codegen/src/main/resources/bash/README.mustache

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
## Overview
44
This is a Bash client script for accessing {{appName}} service.
55

6-
The script uses cURL underneath for making all REST calls.
6+
The script uses cURL underneath for making all REST calls.
77

88
## Usage
99

@@ -86,3 +86,41 @@ fi
8686

8787
### Zsh
8888
In Zsh, the generated `_{{scriptName}}` Zsh completion file must be copied to one of the folders under `$FPATH` variable.
89+
90+
91+
## Documentation for API Endpoints
92+
93+
All URIs are relative to *{{basePathWithoutHost}}*
94+
95+
Class | Method | HTTP request | Description
96+
------------ | ------------- | ------------- | -------------
97+
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
98+
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
99+
100+
## Documentation For Models
101+
102+
{{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
103+
{{/model}}{{/models}}
104+
105+
## Documentation For Authorization
106+
107+
{{^authMethods}} All endpoints do not require authorization.
108+
{{/authMethods}}{{#authMethods}}{{#last}} Authentication schemes defined for the API:{{/last}}{{/authMethods}}
109+
{{#authMethods}}## {{{name}}}
110+
111+
{{#isApiKey}}- **Type**: API key
112+
- **API key parameter name**: {{{keyParamName}}}
113+
- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
114+
{{/isApiKey}}
115+
{{#isBasic}}- **Type**: HTTP basic authentication
116+
{{/isBasic}}
117+
{{#isOAuth}}- **Type**: OAuth
118+
- **Flow**: {{{flow}}}{{#authorizationUrl}}
119+
- **Authorization URL**: {{{authorizationUrl}}}{{/authorizationUrl}}{{#tokenUrl}}
120+
- **Token URL**: {{{tokenUrl}}}{{/tokenUrl}}
121+
- **Scopes**:{{^scopes}} N/A{{/scopes}}
122+
{{#scopes}} - **{{{scope}}}**: {{{description}}}
123+
{{/scopes}}
124+
{{/isOAuth}}
125+
126+
{{/authMethods}}

‎modules/swagger-codegen/src/main/resources/bash/api_doc.mustache

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# {{classname}}{{#description}}
2+
{{description}}{{/description}}
3+
4+
All URIs are relative to *{{basePathWithoutHost}}*
5+
6+
Method | HTTP request | Description
7+
------------- | ------------- | -------------
8+
{{#operations}}{{#operation}}[**{{operationId}}**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
9+
{{/operation}}{{/operations}}
10+
11+
{{#operations}}
12+
{{#operation}}
13+
## **{{{operationId}}}**
14+
15+
{{{summary}}}{{#notes}}
16+
17+
{{{notes}}}{{/notes}}
18+
19+
### Example
20+
```bash
21+
{{scriptName}} {{operationId}}{{#allParams}}{{#isPathParam}} {{baseName}}=value{{/isPathParam}}{{#isQueryParam}} {{#isContainer}} Specify as: {{#vendorExtensions}}{{#x-codegen-collection-multi}} {{baseName}}=value1 {{baseName}}=value2 {{baseName}}=...{{/x-codegen-collection-multi}}{{#x-codegen-collection-csv}} {{baseName}}="value1,value2,..."{{/x-codegen-collection-csv}}{{#x-codegen-collection-pipes}} {{baseName}}="value1|value2|..."{{/x-codegen-collection-pipes}}{{#x-codegen-collection-ssv}} {{baseName}}="value1 value2 ..."{{/x-codegen-collection-ssv}}{{#x-codegen-collection-tsv}} {{baseName}}="value1\\tvalue2\\t..."{{/x-codegen-collection-tsv}}{{/vendorExtensions}}{{/isContainer}}{{^isContainer}} {{baseName}}=value{{/isContainer}}{{/isQueryParam}}{{#isHeaderParam}} {{baseName}}:value{{/isHeaderParam}}{{#isBodyParam}}{{#vendorExtensions}}{{#x-codegen-body-example}} '{{{x-codegen-body-example}}}'{{/x-codegen-body-example}}{{/vendorExtensions}}{{/isBodyParam}}{{/allParams}}
22+
```
23+
24+
### Parameters
25+
{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}
26+
Name | Type | Description | Notes
27+
------------- | ------------- | ------------- | -------------{{/-last}}{{/allParams}}
28+
{{#allParams}} **{{paramName}}** | {{#isFile}}**{{dataType}}**{{/isFile}}{{^isFile}}{{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{baseType}}.md){{/isPrimitiveType}}{{/isFile}} | {{{description}}} |{{^required}} [optional]{{/required}}{{#defaultValue}} [default to {{defaultValue}}]{{/defaultValue}}
29+
{{/allParams}}
30+
31+
### Return type
32+
33+
{{#returnType}}{{#returnTypeIsPrimitive}}**{{{returnType}}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}[**{{{returnType}}}**]({{returnBaseType}}.md){{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}(empty response body){{/returnType}}
34+
35+
### Authorization
36+
37+
{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{{name}}}](../README.md#{{{name}}}){{^-last}}, {{/-last}}{{/authMethods}}
38+
39+
### HTTP request headers
40+
41+
- **Content-Type**: {{#consumes}}{{{mediaType}}}{{#hasMore}}, {{/hasMore}}{{/consumes}}{{^consumes}}Not Applicable{{/consumes}}
42+
- **Accept**: {{#produces}}{{{mediaType}}}{{#hasMore}}, {{/hasMore}}{{/produces}}{{^produces}}Not Applicable{{/produces}}
43+
44+
[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
45+
46+
{{/operation}}
47+
{{/operations}}

‎modules/swagger-codegen/src/main/resources/bash/client.mustache

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -577,9 +577,11 @@ EOF
577577
{{#x-codegen-apikey-env}}echo -e " or export ${RED}{{x-codegen-apikey-env}}='<api-key>'${OFF}"{{/x-codegen-apikey-env}}
578578
{{/isApiKey}}
579579
{{#isOAuth}}
580-
echo -e " - ${MAGENTA}OAuth2 (flow: {{flow}})${OFF}"
580+
echo -e " - ${MAGENTA}OAuth2 (flow: {{flow}})${OFF}"{{#authorizationUrl}}
581581
echo -e " Authorization URL: "
582-
echo -e " * {{authorizationUrl}}"
582+
echo -e " * {{authorizationUrl}}"{{/authorizationUrl}}{{#tokenUrl}}
583+
echo -e " Token URL: "
584+
echo -e " * {{tokenUrl}}"{{/tokenUrl}}
583585
echo -e " Scopes:"
584586
{{#scopes}}
585587
echo -e " * {{scope}} - {{description}}"

‎modules/swagger-codegen/src/main/resources/bash/model_doc.mustache

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{{#models}}{{#model}}# {{name}}
2+
3+
## Properties
4+
Name | Type | Description | Notes
5+
------------ | ------------- | ------------- | -------------
6+
{{#vars}}**{{name}}** | {{#isPrimitiveType}}**{{datatype}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{datatype}}**]({{complexType}}.md){{/isPrimitiveType}} | {{title}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}}
7+
{{/vars}}
8+
9+
[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
10+
11+
{{/model}}{{/models}}

0 commit comments

Comments
 (0)