chore(repo): simplify ReadMe and docs for 3.X

docs/building.md

@@ -0,0 +1,31 @@
+# Building
+
+After cloning the project, you can build it from source with this command:
+
+```sh
+mvn clean package
+```
+
+## Homebrew
+
+To install, run `brew install swagger-codegen`
+
+Here is an example usage:
+
+```sh
+swagger-codegen generate -i http://petstore.swagger.io/v2/swagger.json -l ruby -o /tmp/test/
+```
+
+## To build a server stub
+
+Please refer to [wiki](https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO) for more information.
+
+## To build the codegen library
+
+This will create the Swagger Codegen library from source.
+
+```sh
+mvn package
+```
+
+> The templates are included in the library generated.  If you want to modify the templates, you'll need to either repackage the library OR specify a path to your scripts.

docs/docker.md

@@ -0,0 +1,130 @@
+# Docker
+
+## Development in docker
+
+You can use `run-in-docker.sh` to do all development. This script maps your local repository to `/gen`
+in the docker container. It also maps `~/.m2/repository` to the appropriate container location.
+
+To execute `mvn package`:
+
+```sh
+git clone https://github.com/swagger-api/swagger-codegen
+cd swagger-codegen
+./run-in-docker.sh mvn package
+```
+
+Build artifacts are now accessible in your working directory.
+
+Once built, `run-in-docker.sh` will act as an executable for swagger-codegen-cli. To generate code, you'll need to output to a directory under `/gen` (e.g. `/gen/out`). For example:
+
+```sh
+./run-in-docker.sh help # Executes 'help' command for swagger-codegen-cli
+./run-in-docker.sh langs # Executes 'langs' command for swagger-codegen-cli
+./run-in-docker.sh /gen/bin/go-petstore.sh  # Builds the Go client
+./run-in-docker.sh generate -i modules/swagger-codegen/src/test/resources/2_0/petstore.yaml \
+    -l go -o /gen/out/go-petstore -DpackageName=petstore # generates go client, outputs locally to ./out/go-petstore
+```
+
+## Standalone generator Development in docker
+
+See [standalone generator development](https://github.com/swagger-api/swagger-codegen/blob/3.0.0/standalone-gen-dev/standalone-generator-development.md)
+
+## Run Docker in Vagrant
+
+Prerequisite: install [Vagrant](https://www.vagrantup.com/downloads.html) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads).
+
+ ```sh
+git clone http://github.com/swagger-api/swagger-codegen.git
+cd swagger-codegen
+vagrant up
+vagrant ssh
+cd /vagrant
+./run-in-docker.sh mvn package
+ ```
+
+## Public Pre-built Docker images
+
+- [Official web service](https://hub.docker.com/r/swaggerapi/swagger-generator-v3/)
+- [Official web service with "standard" user](https://hub.docker.com/r/swaggerapi/swagger-generator-v3-root/)
+- [official minimal web service](https://hub.docker.com/r/swaggerapi/swagger-generator-v3-minimal/)
+- [official CLI](https://hub.docker.com/r/swaggerapi/swagger-codegen-cli-v3/)
+
+### Swagger Generator Docker Image
+
+The Swagger Generator image provides a ready to use web application (swagger-generator) providing code generation services.
+
+Image accepts the following env variables:
+
+- `JAVA_MEM` e.g. `1024m`
+- `HTTP_PORT` e.g. `8080`
+- `HIDDEN_OPTIONS_PATH` (alternative to `HIDDEN_OPTIONS`): useful if attaching a volume containing a `hiddenOptions.yaml` file definining which languages to hide. e.g. `/data/hiddenOptions.yaml`
+- `HIDDEN_OPTIONS` (alternative to `HIDDEN_OPTIONS_PATH`): allows to pass hidden options as an env variable, in the format `{category}:{language},{language},{language}|{category}:{language},{language},{language}`
+e.g. `servers:foo,bar|clientsV3:wtf,isthis` where category can be `clients`, `servers`, `clientsV3`, `serversV3`
+
+An example of running the container:
+
+`docker pull swaggerapi/swagger-generator-v3`
+
+`docker run -e "HIDDEN_OPTIONS=servers:foo,bar|clientsV3:fgf,sdsd" -e "JAVA_MEM=1024m" -e "HTTP_PORT=80" -p 80:80 --name swagger-generator-v3 -v /tmp:/jetty_home/lib/shared swaggerapi/swagger-generator-v3`
+
+or
+
+`docker run -e "HIDDEN_OPTIONS_PATH=/hiddenOptions.yaml" -e "JAVA_MEM=1024m" -e "HTTP_PORT=80" -p 80:80 --name swagger-generator-v3  -v /tmp:/jetty_home/lib/shared swaggerapi/swagger-generator-v3`
+
+This docker image supports custom generators by dropping the generator jar into `/jetty_home/lib/shared` directory (typically via a docker volume); e.g having on host `/my/custom/coolgenerator.jar` and `/my/custom/weirdgenerator.jar`  the following would have them added to generator service generators:
+
+`docker run -e "HIDDEN_OPTIONS_PATH=/hiddenOptions.yaml" -e "JAVA_MEM=1024m" -e "HTTP_PORT=80" -p 80:80 --name swagger-generator-v3 -v /my/custom:/jetty_home/lib/shared swaggerapi/swagger-generator-v3`
+
+Please note that up to version 3.0.20 you need to provide`-v /{WHATEVER_DIR}:/jetty_home/lib/shared` even if not using custom generators.
+
+See also [online generators](./online-generators.md).
+
+### Swagger Generator "Minimal" Docker Image
+
+The Swagger Generator "Minimal" image can act as a self-hosted web application and API for generating code.
+
+This container can be incorporated into a CI pipeline, and requires some docker orchestration to access generated code.
+
+Example usage:
+
+```sh
+# Start container and save the container id
+CID=$(docker run -d swaggerapi/swagger-generator-v3-minimal)
+# allow for startup
+sleep 5
+# Get the IP of the running container
+GEN_IP=$(docker inspect --format '{{.NetworkSettings.IPAddress}}'  $CID)
+# Execute an HTTP request and store the download link
+curl -X POST \
+           http://localhost:8080/api/generate \
+           -H 'content-type: application/json' \
+           -d '{
+           "specURL" : "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml",
+           "lang" : "jaxrs-jersey",
+           "type" : "SERVER",
+           "codegenVersion" : "V3"
+         }' > result.zip
+# Shutdown the swagger generator image
+docker stop $CID && docker rm $CID
+```
+
+In the example above, `result.zip` will contain the generated client.
+
+See also [online generators](../README.md#online-generators).
+
+### Swagger Codegen CLI Docker Image
+
+The Swagger Codegen image acts as a standalone executable. It can be used as an alternative to installing via homebrew, or for developers who are unable to install Java or upgrade the installed version.
+
+To generate code with this image, you'll need to mount a local location as a volume.
+
+Example:
+
+```sh
+docker run --rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli-v3 generate \
+    -i http://petstore.swagger.io/v2/swagger.json \
+    -l go \
+    -o /local/out/go
+```
+
+The generated code will be located under `./out/go` in the current directory.

docs/generation-selective.md

@@ -0,0 +1,93 @@
+# Selective Generation
+
+You may not want to generate *all* models in your project.  Likewise you may want just one or two apis to be written.  If that's the case, you can use system properties to control the output:
+
+The default is generate *everything* supported by the specific library.  Once you enable a feature, it will restrict the contents generated:
+
+```sh
+# generate only models
+java -Dmodels {opts}
+
+# generate only apis
+java -Dapis {opts}
+
+# generate only supporting files
+java -DsupportingFiles
+
+# generate models and supporting files
+java -Dmodels -DsupportingFiles
+```
+
+To control the specific files being generated, you can pass a CSV list of what you want:
+
+```sh
+# generate the User and Pet models only
+-Dmodels=User,Pet
+
+# generate the User model and the supportingFile `StringUtil.java`:
+-Dmodels=User -DsupportingFiles=StringUtil.java
+```
+
+To control generation of docs and tests for api and models, pass false to the option. For api, these options are  `-DapiTests=false` and `-DapiDocs=false`. For models, `-DmodelTests=false` and `-DmodelDocs=false`.
+These options default to true and don't limit the generation of the feature options listed above (like `-Dapi`):
+
+```sh
+# generate only models (with tests and documentation)
+java -Dmodels {opts}
+
+# generate only models (with tests but no documentation)
+java -Dmodels -DmodelDocs=false {opts}
+
+# generate only User and Pet models (no tests and no documentation)
+java -Dmodels=User,Pet -DmodelTests=false {opts}
+
+# generate only apis (without tests)
+java -Dapis -DapiTests=false {opts}
+
+# generate only apis (modelTests option is ignored)
+java -Dapis -DmodelTests=false {opts}
+```
+
+When using selective generation, _only_ the templates needed for the specific generation will be used.
+
+## Ignore file format
+
+Swagger Codegen supports a `.swagger-codegen-ignore` file, similar to `.gitignore` or `.dockerignore` you're probably already familiar with.
+
+The ignore file allows for better control over overwriting existing files than the `--skip-overwrite` flag. With the ignore file, you can specify individual files or directories can be ignored. This can be useful, for example if you only want a subset of the generated code.
+
+Examples:
+
+```sh
+# Swagger Codegen Ignore
+# Lines beginning with a # are comments
+
+# This should match build.sh located anywhere.
+build.sh
+
+# Matches build.sh in the root
+/build.sh
+
+# Exclude all recursively
+docs/**
+
+# Explicitly allow files excluded by other rules
+!docs/UserApi.md
+
+# Recursively exclude directories named Api
+# You can't negate files below this directory.
+src/**/Api/
+
+# When this file is nested under /Api (excluded above),
+# this rule is ignored because parent directory is excluded by previous rule.
+!src/**/PetApiTests.cs
+
+# Exclude a single, nested file explicitly
+src/IO.Swagger.Test/Model/AnimalFarmTests.cs
+```
+
+The `.swagger-codegen-ignore` file must exist in the root of the output directory.
+
+Upon first code generation, you may also pass the CLI option `--ignore-file-override=/path/to/ignore_file` for greater control over generated outputs. Note that this is a complete override, and will override the `.swagger-codegen-ignore` file in an output directory when regenerating code.
+
+Editor support for `.swagger-codegen-ignore` files is available in IntelliJ via the [.ignore plugin](https://plugins.jetbrains.com/plugin/7495--ignore).

docs/generators-configuration.md

@@ -0,0 +1,121 @@
+# Advanced Generator Configuration
+
+There are different aspects of customizing the code generator (located in this version at [swagger codegen generator repo](https://github.com/swagger-api/swagger-codegen-generators)) beyond just creating or modifying templates.  Each language has a supporting configuration file to handle different type mappings, etc:
+
+```sh
+s -1 modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/
+
+AbstractJavaCodegen.java
+AbstractJavaJAXRSServerCodegen.java
+... (results omitted)
+JavaClientCodegen.java
+JavaJAXRSSpecServerCodegen.java
+```
+
+Each of these files creates reasonable defaults so you can get running quickly. If you want to configure package names, prefixes, model folders, etc. you can use a JSON config file to pass the values.
+
+```sh
+java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
+  -i http://petstore.swagger.io/v2/swagger.json \
+  -l java \
+  -o samples/client/petstore/java \
+  -c path/to/config.json
+```
+
+and `config.json` contains the following as an example:
+
+```json
+{
+  "apiPackage" : "petstore"
+}
+```
+
+Supported config options can be different per language. Running `config-help -l {lang}` will show available options.
+**These options are applied via configuration file (e.g. config.json) or by passing them with `-D{optionName}={optionValue}`**. (If `-D{optionName}` does not work, please open a [ticket](https://github.com/swagger-api/swagger-codegen/issues/new) and we'll look into it)
+
+```sh
+java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l java
+```
+
+Output:
+
+```text
+CONFIG OPTIONS
+modelPackage
+    package for generated models
+
+apiPackage
+    package for generated api classes
+...... (results omitted)
+library
+    library template (sub-template) to use:
+    jersey1 - HTTP client: Jersey client 1.18. JSON processing: Jackson 2.4.2
+    jersey2 - HTTP client: Jersey client 2.6
+    feign - HTTP client: Netflix Feign 8.1.1.  JSON processing: Jackson 2.6.3
+    okhttp-gson (default) - HTTP client: OkHttp 2.4.0. JSON processing: Gson 2.3.1
+    retrofit - HTTP client: OkHttp 2.4.0. JSON processing: Gson 2.3.1 (Retrofit 1.9.0)
+    retrofit2 - HTTP client: OkHttp 2.5.0. JSON processing: Gson 2.4 (Retrofit 2.0.0-beta2)
+    google-api-client - HTTP client: google-api-client 1.23.0. JSON processing: Jackson 2.8.9
+```
+
+Your config file for Java can look like
+
+```json
+{
+  "groupId":"com.my.company",
+  "artifactId":"MyClient",
+  "artifactVersion":"1.2.0",
+  "library":"feign"
+}
+```
+
+For all the unspecified options default values will be used.
+
+Another way to override default options is to extend the config class for the specific language.
+To change, for example, the prefix for the Objective-C generated files, simply subclass the ObjcClientCodegen.java:
+
+```java
+package com.mycompany.swagger.codegen;
+
+import io.swagger.codegen.languages.*;
+
+public class MyObjcCodegen extends ObjcClientCodegen {
+    static {
+        PREFIX = "HELO";
+    }
+}
+```
+
+and specify the `classname` when running the generator:
+
+```sh
+-l com.mycompany.swagger.codegen.MyObjcCodegen
+```
+
+Your subclass will now be loaded and overrides the `PREFIX` value in the superclass.
+
+## Bringing your own models
+
+Sometimes you don't want a model generated.  In this case, you can simply specify an import mapping to tell
+the codegen what _not_ to create.  When doing this, every location that references a specific model will
+refer back to your classes.  
+
+> Note, this may not apply to all languages!
+
+To specify an import mapping, use the `--import-mappings` argument and specify the model-to-import logic as such:
+
+```sh
+--import-mappings Pet=my.models.MyPet
+```
+
+Or for multiple mappings:
+
+```sh
+--import-mappings Pet=my.models.MyPet,Order=my.models.MyOrder
+```
+
+or
+
+```sh
+--import-mappings Pet=my.models.MyPet --import-mappings Order=my.models.MyOrder
+```