Feature: Adds doc generation (#6570)

Reference #2359
swagger-api · Sep 28, 2017 · d04b764 · d04b764
1 parent 2c7dcbe
commit d04b764
Show file tree

Hide file tree

Showing 48 changed files with 1,815 additions and 31 deletions.
diff --git a/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/BashClientCodegen.java b/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/BashClientCodegen.java
@@ -39,7 +39,8 @@ public class BashClientCodegen extends DefaultCodegen implements CodegenConfig {
   protected String hostEnvironmentVariable;
   protected String basicAuthEnvironmentVariable;
   protected String apiKeyAuthEnvironmentVariable;
-
+  protected String apiDocPath = "docs/";
+  protected String modelDocPath = "docs/";
 
   public static final String CURL_OPTIONS = "curlOptions";
   public static final String PROCESS_MARKDOWN = "processMarkdown";
@@ -105,6 +106,13 @@ public BashClientCodegen() {
     apiTemplateFiles.clear();
 
 
+    /**
+     * docs files.
+     */
+    modelDocTemplateFiles.put("model_doc.mustache", ".md");
+    apiDocTemplateFiles.put("api_doc.mustache", ".md");
+
+
     /**
      * Templates location for client script and bash completion template.
      */
@@ -169,6 +177,7 @@ public BashClientCodegen() {
     typeMapping.put("int", "integer");
     typeMapping.put("float", "float");
     typeMapping.put("number", "integer");
+    typeMapping.put("date", "string");
     typeMapping.put("DateTime", "string");
     typeMapping.put("long", "integer");
     typeMapping.put("short", "integer");
@@ -185,12 +194,22 @@ public BashClientCodegen() {
      * are available in models, apis, and supporting files.
      */
     additionalProperties.put("apiVersion", apiVersion);
+    // make api and model doc path available in mustache template
+    additionalProperties.put("apiDocPath", apiDocPath);
+    additionalProperties.put("modelDocPath", modelDocPath);
 
     /**
      * Language Specific Primitives.  These types will not trigger imports by
      * the client generator
      */
-    languageSpecificPrimitives = new HashSet<String>();
+    languageSpecificPrimitives.clear();
+    languageSpecificPrimitives.add("array");
+    languageSpecificPrimitives.add("map");
+    languageSpecificPrimitives.add("boolean");
+    languageSpecificPrimitives.add("integer");
+    languageSpecificPrimitives.add("float");
+    languageSpecificPrimitives.add("string");
+    languageSpecificPrimitives.add("binary");
   }
 
 
@@ -239,15 +258,15 @@ public void processOpts() {
       }
 
       supportingFiles.add(new SupportingFile(
-                                          "client.mustache",  "", scriptName));
+              "client.mustache",  "", scriptName));
       supportingFiles.add(new SupportingFile(
-               "bash-completion.mustache", "", scriptName+".bash-completion"));
+              "bash-completion.mustache", "", scriptName+".bash-completion"));
       supportingFiles.add(new SupportingFile(
-               "zsh-completion.mustache", "", "_"+scriptName));
+              "zsh-completion.mustache", "", "_"+scriptName));
       supportingFiles.add(new SupportingFile(
-               "README.mustache", "", "README.md"));
+              "README.mustache", "", "README.md"));
       supportingFiles.add(new SupportingFile(
-               "Dockerfile.mustache", "", "Dockerfile"));
+              "Dockerfile.mustache", "", "Dockerfile"));
   }
 
   public void setCurlOptions(String curlOptions) {
@@ -314,6 +333,25 @@ public String apiFileFolder() {
     return outputFolder;
   }
 
+  @Override
+  public String apiDocFileFolder() {
+    return (outputFolder + "/" + apiDocPath);
+  }
+
+  @Override
+  public String modelDocFileFolder() {
+    return (outputFolder + "/" + modelDocPath);
+  }
+
+  @Override
+  public String toModelDocFilename(String name) {
+    return toModelName(name);
+  }
+
+  @Override
+  public String toApiDocFilename(String name) {
+    return toApiName(name);
+  }
 
   /**
    * Optional - type declaration. This is a String which is used by the
@@ -355,8 +393,9 @@ public String getSwaggerType(Property p) {
       if(languageSpecificPrimitives.contains(type))
         return type;
     }
-    else
+    else {
       type = swaggerType;
+    }
     return toModelName(type);
   }
 
@@ -656,4 +695,69 @@ public void preprocessSwagger(Swagger swagger) {
 
   }
 
+  @Override
+  public void setParameterExampleValue(CodegenParameter p) {
+      String example;
+
+      if (p.defaultValue == null) {
+          example = p.example;
+      } else {
+          example = p.defaultValue;
+      }
+
+      String type = p.baseType;
+      if (type == null) {
+          type = p.dataType;
+      }
+
+      if ("string".equalsIgnoreCase(type)) {
+          if (example == null) {
+              example = p.paramName + "_example";
+          }
+          example = "'" + escapeText(example) + "'";
+      } else if ("integer".equals(type)) {
+          if (example == null) {
+              example = "56";
+          }
+      } else if ("float".equalsIgnoreCase(type)) {
+          if (example == null) {
+              example = "3.4";
+          }
+      } else if ("boolean".equalsIgnoreCase(type)) {
+          if (example == null) {
+              example = "True";
+          }
+      } else if ("file".equalsIgnoreCase(type)) {
+          if (example == null) {
+              example = "/path/to/file";
+          }
+          example = "'" + escapeText(example) + "'";
+      } else if ("date".equalsIgnoreCase(type)) {
+          if (example == null) {
+              example = "2013-10-20";
+          }
+          example = "'" + escapeText(example) + "'";
+      } else if ("datetime".equalsIgnoreCase(type)) {
+          if (example == null) {
+              example = "2013-10-20T19:20:30+01:00";
+          }
+          example = "'" + escapeText(example) + "'";
+      } else if (!languageSpecificPrimitives.contains(type)) {
+          // type is a model class, e.g. User
+          example = type;
+      } else {
+          LOGGER.warn("Type " + type + " not handled properly in setParameterExampleValue");
+      }
+
+      if (example == null) {
+          example = "NULL";
+      } else if (Boolean.TRUE.equals(p.isListContainer)) {
+          example = "[" + example + "]";
+      } else if (Boolean.TRUE.equals(p.isMapContainer)) {
+          example = "{'key': " + example + "}";
+      }
+
+      p.example = example;
+  }
+
 }
diff --git a/modules/swagger-codegen/src/main/resources/bash/README.mustache b/modules/swagger-codegen/src/main/resources/bash/README.mustache
@@ -3,7 +3,7 @@
 ## Overview
 This is a Bash client script for accessing {{appName}} service.
 
-The script uses  cURL underneath for making all REST calls.
+The script uses cURL underneath for making all REST calls.
 
 ## Usage
 
@@ -86,3 +86,41 @@ fi
 
 ### Zsh
 In Zsh, the generated `_{{scriptName}}` Zsh completion file must be copied to one of the folders under `$FPATH` variable.
+
+
+## Documentation for API Endpoints
+
+All URIs are relative to *{{basePathWithoutHost}}*
+
+Class | Method | HTTP request | Description
+------------ | ------------- | ------------- | -------------
+{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
+{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
+
+## Documentation For Models
+
+{{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
+{{/model}}{{/models}}
+
+## Documentation For Authorization
+
+{{^authMethods}} All endpoints do not require authorization.
+{{/authMethods}}{{#authMethods}}{{#last}} Authentication schemes defined for the API:{{/last}}{{/authMethods}}
+{{#authMethods}}## {{{name}}}
+
+{{#isApiKey}}- **Type**: API key
+- **API key parameter name**: {{{keyParamName}}}
+- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
+{{/isApiKey}}
+{{#isBasic}}- **Type**: HTTP basic authentication
+{{/isBasic}}
+{{#isOAuth}}- **Type**: OAuth
+- **Flow**: {{{flow}}}{{#authorizationUrl}}
+- **Authorization URL**: {{{authorizationUrl}}}{{/authorizationUrl}}{{#tokenUrl}}
+- **Token URL**: {{{tokenUrl}}}{{/tokenUrl}}
+- **Scopes**:{{^scopes}} N/A{{/scopes}}
+{{#scopes}}  - **{{{scope}}}**: {{{description}}}
+{{/scopes}}
+{{/isOAuth}}
+
+{{/authMethods}}
diff --git a/modules/swagger-codegen/src/main/resources/bash/api_doc.mustache b/modules/swagger-codegen/src/main/resources/bash/api_doc.mustache
@@ -0,0 +1,47 @@
+# {{classname}}{{#description}}
+{{description}}{{/description}}
+
+All URIs are relative to *{{basePathWithoutHost}}*
+
+Method | HTTP request | Description
+------------- | ------------- | -------------
+{{#operations}}{{#operation}}[**{{operationId}}**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
+{{/operation}}{{/operations}}
+
+{{#operations}}
+{{#operation}}
+## **{{{operationId}}}**
+
+{{{summary}}}{{#notes}}
+
+{{{notes}}}{{/notes}}
+
+### Example
+```bash
+{{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}}
+```
+
+### Parameters
+{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------{{/-last}}{{/allParams}}
+{{#allParams}} **{{paramName}}** | {{#isFile}}**{{dataType}}**{{/isFile}}{{^isFile}}{{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{baseType}}.md){{/isPrimitiveType}}{{/isFile}} | {{{description}}} |{{^required}} [optional]{{/required}}{{#defaultValue}} [default to {{defaultValue}}]{{/defaultValue}}
+{{/allParams}}
+
+### Return type
+
+{{#returnType}}{{#returnTypeIsPrimitive}}**{{{returnType}}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}[**{{{returnType}}}**]({{returnBaseType}}.md){{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}(empty response body){{/returnType}}
+
+### Authorization
+
+{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{{name}}}](../README.md#{{{name}}}){{^-last}}, {{/-last}}{{/authMethods}}
+
+### HTTP request headers
+
+ - **Content-Type**: {{#consumes}}{{{mediaType}}}{{#hasMore}}, {{/hasMore}}{{/consumes}}{{^consumes}}Not Applicable{{/consumes}}
+ - **Accept**: {{#produces}}{{{mediaType}}}{{#hasMore}}, {{/hasMore}}{{/produces}}{{^produces}}Not Applicable{{/produces}}
+
+[[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)
+
+{{/operation}}
+{{/operations}}
diff --git a/modules/swagger-codegen/src/main/resources/bash/client.mustache b/modules/swagger-codegen/src/main/resources/bash/client.mustache
@@ -577,9 +577,11 @@ EOF
     {{#x-codegen-apikey-env}}echo -e "              or export ${RED}{{x-codegen-apikey-env}}='<api-key>'${OFF}"{{/x-codegen-apikey-env}}
 {{/isApiKey}}
 {{#isOAuth}}
-    echo -e "  - ${MAGENTA}OAuth2 (flow: {{flow}})${OFF}"
+    echo -e "  - ${MAGENTA}OAuth2 (flow: {{flow}})${OFF}"{{#authorizationUrl}}
     echo -e "      Authorization URL: "
-    echo -e "        * {{authorizationUrl}}"
+    echo -e "        * {{authorizationUrl}}"{{/authorizationUrl}}{{#tokenUrl}}
+    echo -e "      Token URL: "
+    echo -e "        * {{tokenUrl}}"{{/tokenUrl}}
     echo -e "      Scopes:"
 {{#scopes}}
     echo -e "        * {{scope}} - {{description}}"

diff --git a/modules/swagger-codegen/src/main/resources/bash/model_doc.mustache b/modules/swagger-codegen/src/main/resources/bash/model_doc.mustache
@@ -0,0 +1,11 @@
+{{#models}}{{#model}}# {{name}}
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+{{#vars}}**{{name}}** | {{#isPrimitiveType}}**{{datatype}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{datatype}}**]({{complexType}}.md){{/isPrimitiveType}} | {{title}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{{.}}}]{{/defaultValue}}
+{{/vars}}
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+{{/model}}{{/models}}