diff --git a/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/JavaClientCodegen.java b/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/JavaClientCodegen.java
index fae47c70729d..7e0aa4ca0fd9 100644
--- a/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/JavaClientCodegen.java
+++ b/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/JavaClientCodegen.java
@@ -42,6 +42,8 @@ public class JavaClientCodegen extends DefaultCodegen implements CodegenConfig {
     protected Boolean serializableModel = false;
     protected boolean serializeBigDecimalAsString = false;
     protected boolean useRxJava = false;
+    protected String apiDocPath = "docs/";
+    protected String modelDocPath = "docs/";
 
     public JavaClientCodegen() {
         super();
@@ -205,6 +207,10 @@ public class JavaClientCodegen extends DefaultCodegen implements CodegenConfig {
         additionalProperties.put(FULL_JAVA_UTIL, fullJavaUtil);
         additionalProperties.put("javaUtilPrefix", javaUtilPrefix);
 
+        // make api and model doc path available in mustache template
+        additionalProperties.put("apiDocPath", apiDocPath);
+        additionalProperties.put("modelDocPath", modelDocPath);
+
         importMapping.put("List", "java.util.List");
 
         if (fullJavaUtil) {
@@ -266,7 +272,10 @@ public class JavaClientCodegen extends DefaultCodegen implements CodegenConfig {
         }
 
         // library-specific files
-        if ("okhttp-gson".equals(getLibrary())) {
+        if (StringUtils.isEmpty(getLibrary())) {
+            modelDocTemplateFiles.put("model_doc.mustache", ".md");
+            apiDocTemplateFiles.put("api_doc.mustache", ".md");
+        } else if ("okhttp-gson".equals(getLibrary())) {
             // the "okhttp-gson" library template requires "ApiCallback.mustache" for async call
             supportingFiles.add(new SupportingFile("ApiCallback.mustache", invokerFolder, "ApiCallback.java"));
             supportingFiles.add(new SupportingFile("ApiResponse.mustache", invokerFolder, "ApiResponse.java"));
@@ -350,6 +359,26 @@ public class JavaClientCodegen extends DefaultCodegen implements CodegenConfig {
         return outputFolder + "/" + sourceFolder + "/" + modelPackage().replace('.', '/');
     }
 
+    @Override
+    public String apiDocFileFolder() {
+        return (outputFolder + "/" + apiDocPath).replace('/', File.separatorChar);
+    }
+
+    @Override
+    public String modelDocFileFolder() {
+        return (outputFolder + "/" + modelDocPath).replace('/', File.separatorChar);
+    }
+
+    @Override
+    public String toApiDocFilename(String name) {
+        return toApiName(name);
+    }
+
+    @Override
+    public String toModelDocFilename(String name) {
+        return toModelName(name);
+    }
+
     @Override
     public String toVarName(String name) {
         // sanitize name
@@ -494,6 +523,69 @@ public class JavaClientCodegen extends DefaultCodegen implements CodegenConfig {
         return super.toDefaultValue(p);
     }
 
+    @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".equals(type)) {
+            if (example == null) {
+                example = p.paramName + "_example";
+            }
+            example = "\"" + escapeText(example) + "\"";
+        } else if ("Integer".equals(type) || "Short".equals(type)) {
+            if (example == null) {
+                example = "56";
+            }
+        } else if ("Long".equals(type)) {
+            if (example == null) {
+                example = "56L";
+            }
+        } else if ("Float".equals(type)) {
+            if (example == null) {
+                example = "3.4F";
+            }
+        } else if ("Double".equals(type)) {
+            if (example == null) {
+                example = "3.4D";
+            }
+        } else if ("Boolean".equals(type)) {
+            if (example == null) {
+                example = "true";
+            }
+        } else if ("File".equals(type)) {
+            if (example == null) {
+                example = "/path/to/file";
+            }
+            example = "new File(\"" + escapeText(example) + "\")";
+        } else if ("Date".equals(type)) {
+            example = "new Date()";
+        } else if (!languageSpecificPrimitives.contains(type)) {
+            // type is a model class, e.g. User
+            example = "new " + type + "()";
+        }
+
+        if (example == null) {
+            example = "null";
+        } else if (Boolean.TRUE.equals(p.isListContainer)) {
+            example = "Arrays.asList(" + example + ")";
+        } else if (Boolean.TRUE.equals(p.isMapContainer)) {
+            example = "new HashMap()";
+        }
+
+        p.example = example;
+    }
+
     @Override
     public String getSwaggerType(Property p) {
         String swaggerType = super.getSwaggerType(p);
diff --git a/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/JavascriptClientCodegen.java b/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/JavascriptClientCodegen.java
index d9c93e4f69ea..9915f28be37f 100644
--- a/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/JavascriptClientCodegen.java
+++ b/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/JavascriptClientCodegen.java
@@ -524,26 +524,6 @@ public class JavascriptClientCodegen extends DefaultCodegen implements CodegenCo
             type = p.dataType;
         }
 
-        typeMapping.put("array", "Array");
-        typeMapping.put("List", "Array");
-        typeMapping.put("map", "Object");
-        typeMapping.put("object", "Object");
-        typeMapping.put("boolean", "Boolean");
-        typeMapping.put("char", "String");
-        typeMapping.put("string", "String");
-        typeMapping.put("short", "Integer");
-        typeMapping.put("int", "Integer");
-        typeMapping.put("integer", "Integer");
-        typeMapping.put("long", "Integer");
-        typeMapping.put("float", "Number");
-        typeMapping.put("double", "Number");
-        typeMapping.put("number", "Number");
-        typeMapping.put("DateTime", "Date");
-        typeMapping.put("Date", "Date");
-        typeMapping.put("file", "File");
-        // binary not supported in JavaScript client right now, using String as a workaround
-        typeMapping.put("binary", "String");
-
         if ("String".equals(type)) {
             if (example == null) {
                 example = p.paramName + "_example";
diff --git a/modules/swagger-codegen/src/main/resources/Java/api_doc.mustache b/modules/swagger-codegen/src/main/resources/Java/api_doc.mustache
new file mode 100644
index 000000000000..6249e9b12d37
--- /dev/null
+++ b/modules/swagger-codegen/src/main/resources/Java/api_doc.mustache
@@ -0,0 +1,82 @@
+# {{classname}}{{#description}}
+{{description}}{{/description}}
+
+All URIs are relative to *{{basePath}}*
+
+Method | HTTP request | Description
+------------- | ------------- | -------------
+{{#operations}}{{#operation}}[**{{operationId}}**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
+{{/operation}}{{/operations}}
+
+{{#operations}}
+{{#operation}}
+<a name="{{operationId}}"></a>
+# **{{operationId}}**
+> {{#returnType}}{{returnType}} {{/returnType}}{{operationId}}({{#allParams}}{{{paramName}}}{{#hasMore}}, {{/hasMore}}{{/allParams}})
+
+{{summary}}{{#notes}}
+
+{{notes}}{{/notes}}
+
+### Example
+```java
+// Import classes:{{#hasAuthMethods}}
+//import {{{invokerPackage}}}.ApiClient;{{/hasAuthMethods}}
+//import {{{invokerPackage}}}.ApiException;{{#hasAuthMethods}}
+//import {{{invokerPackage}}}.Configuration;
+//import {{{invokerPackage}}}.auth.*;{{/hasAuthMethods}}
+//import {{{package}}}.{{{classname}}};
+
+{{#hasAuthMethods}}
+ApiClient defaultClient = Configuration.getDefaultApiClient();
+{{#authMethods}}{{#isBasic}}
+// Configure HTTP basic authorization: {{{name}}}
+HttpBasicAuth {{{name}}} = (HttpBasicAuth) defaultClient.getAuthentication("{{{name}}}");
+{{{name}}}.setUsername("YOUR USERNAME");
+{{{name}}}.setPassword("YOUR PASSWORD");{{/isBasic}}{{#isApiKey}}
+// Configure API key authorization: {{{name}}}
+ApiKeyAuth {{{name}}} = defaultClient.getAuthentication("{{{name}}}");
+{{{name}}}.setApiKey("YOUR API KEY");
+// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
+//{{{name}}}.setApiKeyPrefix("Token");{{/isApiKey}}{{#isOAuth}}
+// Configure OAuth2 access token for authorization: {{{name}}}
+OAuth {{{name}}} = defaultClient.getAuthentication("{{{name}}}");
+{{{name}}}.setAccessToken("YOUR ACCESS TOKEN");{{/isOAuth}}
+{{/authMethods}}
+{{/hasAuthMethods}}
+
+{{{classname}}} apiInstance = new {{{classname}}}();
+{{#allParams}}
+{{{dataType}}} {{{paramName}}} = {{{example}}}; // {{{dataType}}} | {{{description}}}
+{{/allParams}}
+try {
+    {{#returnType}}{{{returnType}}} result = {{/returnType}}apiInstance.{{{operationId}}}({{#allParams}}{{{paramName}}}{{#hasMore}}, {{/hasMore}}{{/allParams}});{{#returnType}}
+    System.out.println(result);{{/returnType}}
+} catch (ApiException e) {
+    System.err.println("Exception when calling {{{classname}}}#{{{operationId}}}");
+    e.printStackTrace();
+}
+```
+
+### Parameters
+{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------{{/-last}}{{/allParams}}
+{{#allParams}} **{{paramName}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{#isFile}}**{{dataType}}**{{/isFile}}{{^isFile}}[**{{dataType}}**]({{baseType}}.md){{/isFile}}{{/isPrimitiveType}}| {{description}} | {{^required}}[optional] {{/required}}{{#defaultValue}}[default to {{defaultValue}}]{{/defaultValue}}
+{{/allParams}}
+
+### Return type
+
+{{#returnType}}{{#returnTypeIsPrimitive}}**{{returnType}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}[**{{returnType}}**]({{returnBaseType}}.md){{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}null (empty response body){{/returnType}}
+
+### Authorization
+
+{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{name}}](../README.md#{{name}}){{^-last}}, {{/-last}}{{/authMethods}}
+
+### HTTP reuqest headers
+
+ - **Content-Type**: {{#consumes}}{{mediaType}}{{#hasMore}}, {{/hasMore}}{{/consumes}}{{^consumes}}Not defined{{/consumes}}
+ - **Accept**: {{#produces}}{{mediaType}}{{#hasMore}}, {{/hasMore}}{{/produces}}{{^produces}}Not defined{{/produces}}
+
+{{/operation}}
+{{/operations}}
diff --git a/modules/swagger-codegen/src/main/resources/Java/model_doc.mustache b/modules/swagger-codegen/src/main/resources/Java/model_doc.mustache
new file mode 100644
index 000000000000..322c40e9db4c
--- /dev/null
+++ b/modules/swagger-codegen/src/main/resources/Java/model_doc.mustache
@@ -0,0 +1,9 @@
+{{#models}}{{#model}}# {{classname}}
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+{{#vars}}**{{name}}** | {{#isPrimitiveType}}**{{datatype}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{datatype}}**]({{complexType}}.md){{/isPrimitiveType}} | {{description}} | {{^required}}[optional] {{/required}}{{#readOnly}}[readonly] {{/readOnly}}{{#defaultValue}}[default to {{defaultValue}}]{{/defaultValue}}
+{{/vars}}
+
+{{/model}}{{/models}}
diff --git a/modules/swagger-codegen/src/main/resources/Javascript/api_doc.mustache b/modules/swagger-codegen/src/main/resources/Javascript/api_doc.mustache
index 698b42dfe114..8aea6e0e5df0 100644
--- a/modules/swagger-codegen/src/main/resources/Javascript/api_doc.mustache
+++ b/modules/swagger-codegen/src/main/resources/Javascript/api_doc.mustache
@@ -12,7 +12,7 @@ Method | HTTP request | Description
 {{#operation}}
 <a name="{{operationId}}"></a>
 # **{{operationId}}**
-> {{#returnType}}{{returnType}} {{/returnType}}{{operationId}}{{#hasParams}}({{#allParams}}{{#required}}{{{paramName}}}{{#vendorExtensions.x-codegen-hasMoreRequired}}, {{/vendorExtensions.x-codegen-hasMoreRequired}}{{/required}}{{/allParams}}{{#hasOptionalParams}}{{#vendorExtensions.x-codegen-hasRequiredParams}}, {{/vendorExtensions.x-codegen-hasRequiredParams}}opts{{/hasOptionalParams}}){{/hasParams}}
+> {{#returnType}}{{returnType}} {{/returnType}}{{operationId}}({{#allParams}}{{#required}}{{{paramName}}}{{#vendorExtensions.x-codegen-hasMoreRequired}}, {{/vendorExtensions.x-codegen-hasMoreRequired}}{{/required}}{{/allParams}}{{#hasOptionalParams}}{{#vendorExtensions.x-codegen-hasRequiredParams}}, {{/vendorExtensions.x-codegen-hasRequiredParams}}opts{{/hasOptionalParams}})
 
 {{summary}}{{#notes}}
 
@@ -26,25 +26,25 @@ var defaultClient = {{{moduleName}}}.ApiClient.default;
 {{#authMethods}}{{#isBasic}}
 // Configure HTTP basic authorization: {{{name}}}
 var {{{name}}} = defaultClient.authentications['{{{name}}}'];
-{{{name}}}.username = 'YOUR USERNAME'
-{{{name}}}.password = 'YOUR PASSWORD'{{/isBasic}}{{#isApiKey}}
+{{{name}}}.username = 'YOUR USERNAME';
+{{{name}}}.password = 'YOUR PASSWORD';{{/isBasic}}{{#isApiKey}}
 // Configure API key authorization: {{{name}}}
 var {{{name}}} = defaultClient.authentications['{{{name}}}'];
-{{{name}}}.apiKey = "YOUR API KEY"
+{{{name}}}.apiKey = 'YOUR API KEY';
 // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
-//{{{name}}}.apiKeyPrefix['{{{keyParamName}}}'] = "Token"{{/isApiKey}}{{#isOAuth}}
+//{{{name}}}.apiKeyPrefix = 'Token';{{/isApiKey}}{{#isOAuth}}
 // Configure OAuth2 access token for authorization: {{{name}}}
 var {{{name}}} = defaultClient.authentications['{{{name}}}'];
-{{{name}}}.accessToken = "YOUR ACCESS TOKEN"{{/isOAuth}}
+{{{name}}}.accessToken = 'YOUR ACCESS TOKEN';{{/isOAuth}}
 {{/authMethods}}
 {{/hasAuthMethods}}
 
-var apiInstance = new {{{moduleName}}}.{{{classname}}}(){{#hasParams}}
+var apiInstance = new {{{moduleName}}}.{{{classname}}}();{{#hasParams}}
 {{#vendorExtensions.x-codegen-hasRequiredParams}}{{#allParams}}{{#required}}
-var {{{paramName}}} = {{{example}}}; // {{=< >=}}{<&dataType>}<={{ }}=> {{{description}}}
+var {{{paramName}}} = {{{example}}}; // {{{dataType}}} | {{{description}}}
 {{/required}}{{/allParams}}{{/vendorExtensions.x-codegen-hasRequiredParams}}{{#hasOptionalParams}}
 var opts = { {{#allParams}}{{^required}}
-  '{{{paramName}}}': {{{example}}}{{#vendorExtensions.x-codegen-hasMoreOptional}},{{/vendorExtensions.x-codegen-hasMoreOptional}} // {{=< >=}}{<&dataType>}<={{ }}=> {{{description}}}{{/required}}{{/allParams}}
+  '{{{paramName}}}': {{{example}}}{{#vendorExtensions.x-codegen-hasMoreOptional}},{{/vendorExtensions.x-codegen-hasMoreOptional}} // {{{dataType}}} | {{{description}}}{{/required}}{{/allParams}}
 };{{/hasOptionalParams}}{{/hasParams}}
 {{#usePromises}}
 apiInstance.{{{operationId}}}({{#allParams}}{{#required}}{{{paramName}}}{{#vendorExtensions.x-codegen-hasMoreRequired}}, {{/vendorExtensions.x-codegen-hasMoreRequired}}{{/required}}{{/allParams}}{{#hasOptionalParams}}{{#vendorExtensions.x-codegen-hasRequiredParams}}, {{/vendorExtensions.x-codegen-hasRequiredParams}}opts{{/hasOptionalParams}}).then(function({{#returnType}}data{{/returnType}}) {
@@ -61,7 +61,7 @@ var callback = function(error, data, response) {
     {{#returnType}}console.log('API called successfully. Returned data: ' + data);{{/returnType}}{{^returnType}}console.log('API called successfully.');{{/returnType}}
   }
 };
-api.{{{operationId}}}({{#allParams}}{{#required}}{{{paramName}}}{{#vendorExtensions.x-codegen-hasMoreRequired}}, {{/vendorExtensions.x-codegen-hasMoreRequired}}{{/required}}{{/allParams}}{{#hasOptionalParams}}{{#vendorExtensions.x-codegen-hasRequiredParams}}, {{/vendorExtensions.x-codegen-hasRequiredParams}}opts{{/hasOptionalParams}}{{#hasParams}}, {{/hasParams}}callback);
+apiInstance.{{{operationId}}}({{#allParams}}{{#required}}{{{paramName}}}{{#vendorExtensions.x-codegen-hasMoreRequired}}, {{/vendorExtensions.x-codegen-hasMoreRequired}}{{/required}}{{/allParams}}{{#hasOptionalParams}}{{#vendorExtensions.x-codegen-hasRequiredParams}}, {{/vendorExtensions.x-codegen-hasRequiredParams}}opts{{/hasOptionalParams}}{{#hasParams}}, {{/hasParams}}callback);
 {{/usePromises}}
 ```