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 a54ec4e038a0..decd8daae2a2 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
@@ -202,6 +202,7 @@ public class JavaClientCodegen extends DefaultCodegen implements CodegenConfig {
 
         final String invokerFolder = (sourceFolder + '/' + invokerPackage).replace(".", "/");
         supportingFiles.add(new SupportingFile("pom.mustache", "", "pom.xml"));
+        supportingFiles.add(new SupportingFile("README.mustache", "", "README.md"));
         supportingFiles.add(new SupportingFile("build.gradle.mustache", "", "build.gradle"));
         supportingFiles.add(new SupportingFile("settings.gradle.mustache", "", "settings.gradle"));
         supportingFiles.add(new SupportingFile("gradle.properties.mustache", "", "gradle.properties"));
diff --git a/modules/swagger-codegen/src/main/resources/Java/README.mustache b/modules/swagger-codegen/src/main/resources/Java/README.mustache
new file mode 100644
index 000000000000..7ce9bac3ca05
--- /dev/null
+++ b/modules/swagger-codegen/src/main/resources/Java/README.mustache
@@ -0,0 +1,43 @@
+# {{artifactId}}
+
+## Requirements
+
+Building the API client library requires [Maven](https://maven.apache.org/) to be installed.
+
+## Installation & Usage
+
+To install the API client library to your local Maven repository, simply execute:
+
+```shell
+mvn install
+```
+
+To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:
+
+```shell
+mvn deploy
+```
+
+Refer to the [official documentation](https://maven.apache.org/plugins/maven-deploy-plugin/usage.html) for more information.
+
+After the client libarary is installed/deployed, you can use it in your Maven project by adding the following to your *pom.xml*:
+
+```xml
+<dependency>
+    <groupId>{{groupId}}</groupId>
+    <artifactId>{{artifactId}}</artifactId>
+    <version>{{artifactVersion}}</version>
+    <scope>compile</scope>
+</dependency>
+
+```
+
+## Recommendation
+
+It's recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issue.
+
+## Author
+
+{{#apiInfo}}{{#apis}}{{^hasMore}}{{infoEmail}}
+{{/hasMore}}{{/apis}}{{/apiInfo}}
+
diff --git a/samples/client/petstore/java/default/README.md b/samples/client/petstore/java/default/README.md
new file mode 100644
index 000000000000..8afc37518fc7
--- /dev/null
+++ b/samples/client/petstore/java/default/README.md
@@ -0,0 +1,43 @@
+# swagger-java-client
+
+## Requirements
+
+Building the API client library requires [Maven](https://maven.apache.org/) to be installed.
+
+## Installation & Usage
+
+To install the API client library to your local Maven repository, simply execute:
+
+```shell
+mvn install
+```
+
+To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:
+
+```shell
+mvn deploy
+```
+
+Refer to the [official documentation](https://maven.apache.org/plugins/maven-deploy-plugin/usage.html) for more information.
+
+After the client libarary is installed/deployed, you can use it in your Maven project by adding the following to your *pom.xml*:
+
+```xml
+<dependency>
+    <groupId>io.swagger</groupId>
+    <artifactId>swagger-java-client</artifactId>
+    <version>1.0.0</version>
+    <scope>compile</scope>
+</dependency>
+
+```
+
+## Recommendation
+
+It's recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issue.
+
+## Author
+
+apiteam@swagger.io
+
+
diff --git a/samples/client/petstore/java/jersey2/README.md b/samples/client/petstore/java/jersey2/README.md
new file mode 100644
index 000000000000..473892d23219
--- /dev/null
+++ b/samples/client/petstore/java/jersey2/README.md
@@ -0,0 +1,43 @@
+# swagger-petstore-jersey2
+
+## Requirements
+
+Building the API client library requires [Maven](https://maven.apache.org/) to be installed.
+
+## Installation & Usage
+
+To install the API client library to your local Maven repository, simply execute:
+
+```shell
+mvn install
+```
+
+To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:
+
+```shell
+mvn deploy
+```
+
+Refer to the [official documentation](https://maven.apache.org/plugins/maven-deploy-plugin/usage.html) for more information.
+
+After the client libarary is installed/deployed, you can use it in your Maven project by adding the following to your *pom.xml*:
+
+```xml
+<dependency>
+    <groupId>io.swagger</groupId>
+    <artifactId>swagger-petstore-jersey2</artifactId>
+    <version>1.0.0</version>
+    <scope>compile</scope>
+</dependency>
+
+```
+
+## Recommendation
+
+It's recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issue.
+
+## Author
+
+apiteam@swagger.io
+
+
diff --git a/samples/client/petstore/java/okhttp-gson/README.md b/samples/client/petstore/java/okhttp-gson/README.md
new file mode 100644
index 000000000000..be7ff686b7ac
--- /dev/null
+++ b/samples/client/petstore/java/okhttp-gson/README.md
@@ -0,0 +1,43 @@
+# swagger-petstore-okhttp-gson
+
+## Requirements
+
+Building the API client library requires [Maven](https://maven.apache.org/) to be installed.
+
+## Installation & Usage
+
+To install the API client library to your local Maven repository, simply execute:
+
+```shell
+mvn install
+```
+
+To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:
+
+```shell
+mvn deploy
+```
+
+Refer to the [official documentation](https://maven.apache.org/plugins/maven-deploy-plugin/usage.html) for more information.
+
+After the client libarary is installed/deployed, you can use it in your Maven project by adding the following to your *pom.xml*:
+
+```xml
+<dependency>
+    <groupId>io.swagger</groupId>
+    <artifactId>swagger-petstore-okhttp-gson</artifactId>
+    <version>1.0.0</version>
+    <scope>compile</scope>
+</dependency>
+
+```
+
+## Recommendation
+
+It's recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issue.
+
+## Author
+
+apiteam@swagger.io
+
+
diff --git a/samples/client/petstore/java/retrofit/README.md b/samples/client/petstore/java/retrofit/README.md
new file mode 100644
index 000000000000..b687b09ab262
--- /dev/null
+++ b/samples/client/petstore/java/retrofit/README.md
@@ -0,0 +1,43 @@
+# swagger-petstore-retrofit
+
+## Requirements
+
+Building the API client library requires [Maven](https://maven.apache.org/) to be installed.
+
+## Installation & Usage
+
+To install the API client library to your local Maven repository, simply execute:
+
+```shell
+mvn install
+```
+
+To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:
+
+```shell
+mvn deploy
+```
+
+Refer to the [official documentation](https://maven.apache.org/plugins/maven-deploy-plugin/usage.html) for more information.
+
+After the client libarary is installed/deployed, you can use it in your Maven project by adding the following to your *pom.xml*:
+
+```xml
+<dependency>
+    <groupId>io.swagger</groupId>
+    <artifactId>swagger-petstore-retrofit</artifactId>
+    <version>1.0.0</version>
+    <scope>compile</scope>
+</dependency>
+
+```
+
+## Recommendation
+
+It's recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issue.
+
+## Author
+
+apiteam@swagger.io
+
+