diff --git a/docs/migration-from-swagger-codegen.md b/docs/migration-from-swagger-codegen.md
new file mode 100644
index 0000000000..59a33e089c
--- /dev/null
+++ b/docs/migration-from-swagger-codegen.md
@@ -0,0 +1,128 @@
+## Migration guide: from Swagger Codegen to OpenAPI Generator
+
+OpenAPI Generator is a fork of `swagger-codegen` between version `2.3.1` and `2.4.0`.
+This community-driven version called "OpenAPI Generator" provides similar functionalities and can be used as drop-in replacement.
+This guide explains the major differences in order to help you with the migration.
+
+### New maven coordinates
+
+You can find our released artefact on maven central:
+
+**Core:**
+
+Old:
+
+```
+<dependency>
+    <groupId>io.swagger</groupId>
+    <artifactId>swagger-codegen</artifactId>
+</dependency>
+```
+
+New:
+
+```
+<dependency>
+    <groupId>org.openapitools</groupId>
+    <artifactId>openapi-generator</artifactId>
+</dependency>
+```
+
+**Cli:**
+
+```
+<dependency>
+    <groupId>io.swagger</groupId>
+    <artifactId>swagger-codegen-cli</artifactId>
+</dependency>
+```
+
+New:
+
+```
+<dependency>
+    <groupId>org.openapitools</groupId>
+    <artifactId>openapi-generator-cli</artifactId>
+</dependency>
+```
+
+**Maven plugin:**
+
+```
+<dependency>
+    <groupId>io.swagger</groupId>
+    <artifactId>swagger-codegen-maven-plugin</artifactId>
+</dependency>
+```
+
+New:
+
+```
+<dependency>
+    <groupId>org.openapitools</groupId>
+    <artifactId>openapi-generator-maven-plugin</artifactId>
+</dependency>
+```
+
+
+### New generators names
+
+When you run OpenAPI Generator, you need to select a target language (`-l` option in the cli).
+All languages of `swagger-codegen` have been migrated to `openapi-generator`, but some names were changed, in order to be more consistent.
+
+| name in `swagger-codegen` | name in `openapi-generator`  |
+|--|--|
+| `akka-scala` | `scala-akka` |
+| `scala` | `scala-httpclient` |
+| `jaxrs` | `jaxrs-jersey` |
+| `qt5cpp` | `cpp-qt5` |
+| `swift` | `swift2-deprecated` |
+
+
+### New parameters name
+
+Some parameters were renamed.
+Often you need to replace "Swagger", with "OpenAPI".
+Some examples:
+
+| name in `swagger-codegen` | name in `openapi-generator`  |
+|--|--|
+| `debugSwagger` | `debugOpenAPI` |
+| `GenerateSwaggerMetadata` | `GenerateOpenAPIMetadata` |
+| `swagger.codegen.undertow.apipackage` | `openapi.codegen.undertow.apipackage` |
+| `swagger.codegen.undertow.modelpackage` | `openapi.codegen.undertow.modelpackage` |
+
+
+### Ignore file
+
+`.swagger-codegen-ignore` is replaced by `.openapi-generator-ignore`.
+The syntax inside the file stays the same.
+
+You don't need to rename the file manually, OpenAPI Generator will do it when your run it against an existing an existing output directory.
+(When there is no `.openapi-generator-ignore` in a folder, if a `.swagger-codegen-ignore` file is present it will be considered and renamed to `.openapi-generator-ignore`).
+
+
+### Metadata folder
+
+The metatata folder (to store the `VERSION` file for example) is now called `.openapi-generator/` instead of `.swagger-codegen/`.
+
+
+
+### New default values for the generated code
+
+If you use a generator without specifying each parameter, you might see some differences in the generated code.
+As example the default package name used in the generated code has changed. 
+You need to have a look at the specific value, depending of your target language, but often `Swagger` îs replaced by `OpenAPITools` and `io.swagger` is replaced by `org.openapitools`.
+Concretely if you did not specify anything when you are generating java code, a file `org/openapitools/api/PetApi.java`  might be generated instead of `io/swagger/api/PetApi.java`.
+
+If this is a problem for you, you need to explicitly set the the parameter value in order to match with the `swagger-codgen` default value (`apiPackage` == `io.swagger` in the previous example with the java generator).
+
+
+### New fully qualified name for the classes 
+
+If you have extended some generators in your project, and you are looking for a specific class, replace the  `io.swagger.codegen` package (old name) with `org.openapitools.codegen` package (new name).
+
+Example: `org.openapitools.codegen.DefaultGenerator`
+
+
+[Back to OpenAPI-Generator's README page](../README.md)