chore(repo): simplify README to aid navigation and docs

Author: frankkilcommins

README.md

@@ -0,0 +1,37 @@
+# Building
+
+After cloning the project, you can build it from source with this command:
+
+```sh
+mvn clean package
+```
+
+If you don't have maven installed, you may directly use the included [maven wrapper](https://github.com/takari/maven-wrapper), and build with the command:
+
+```sh
+./mvnw clean package
+```
+
+## Homebrew
+
+To install, run `brew install swagger-codegen`
+
+Here is an example usage:
+
+```sh
+swagger-codegen generate -i https://petstore.swagger.io/v2/swagger.json -l ruby -o /tmp/test/
+```
+
+## To build a server stub
+
+Please refer to 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
+```
+
+Note!  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/Swagger-Codegen-Logo.png

@@ -0,0 +1,159 @@
+# Companies leveraging Swagger Codegen
+
+Here are some companies/projects using Swagger Codegen in production. To add your company/project to the list, please raise a PR.
+
+- [Acando](https://www.acando.de/)
+- [Accengage](https://www.accengage.com/)
+- [Accruent](https://www.accruent.com/)
+- [Activehours](https://www.activehours.com/)
+- [Actonica](https://www.actonica.com)
+- [Acunetix](https://www.acunetix.com/)
+- [Adaptant](https://www.adaptant.io/)
+- [Atlassian](https://www.atlassian.com/)
+- [Autodesk](http://www.autodesk.com/)
+- [Avenida Compras S.A.](https://www.avenida.com.ar)
+- [AYLIEN](http://aylien.com/)
+- [Balance Internet](https://www.balanceinternet.com.au/)
+- [beemo](http://www.beemo.eu)
+- [bitly](https://bitly.com)
+- [BeezUP](http://www.beezup.com)
+- [Box](https://box.com)
+- [Bufferfly Network](https://www.butterflynetinc.com/)
+- [Cachet Financial](http://www.cachetfinancial.com/)
+- [carpolo](http://www.carpolo.co/)
+- [Carus](https://www.carus.com/)
+- [Cisco](http://www.cisco.com/)
+- [CloudBoost](https://www.CloudBoost.io/)
+- [Cloudsmith](https://cloudsmith.io/)
+- [Conplement](http://www.conplement.de/)
+- [Cummins](http://www.cummins.com/)
+- [Cupix](http://www.cupix.com)
+- [DBBest Technologies](https://www.dbbest.com)
+- [DecentFoX](http://decentfox.com/)
+- [DocRaptor](https://docraptor.com)
+- [DocuSign](https://www.docusign.com)
+- [Elastic](https://www.elastic.co/)
+- [Ergon](http://www.ergon.ch/)
+- [Dell EMC](https://www.emc.com/)
+- [eureka](http://eure.jp/)
+- [everystory.us](http://everystory.us)
+- [Expected Behavior](http://www.expectedbehavior.com/)
+- [fashionTrade](https://www.fashiontrade.com/)
+- [Fastly](https://www.fastly.com/)
+- [FINRA](https://github.com/FINRAOS/herd/)
+- [Flat](https://flat.io)
+- [Finder](http://en.finder.pl/)
+- [Fitwell](https://fitwell.co/)
+- [FH Münster - University of Applied Sciences](http://www.fh-muenster.de)
+- [FormAPI](https://formapi.io/)
+- [Fotition](https://www.fotition.com/)
+- [Gear Zero Network](https://www.gearzero.ca)
+- [General Electric](https://www.ge.com/)
+- [Genentech](https://gene.com)
+- [Genesys - PureCloud](http://developer.mypurecloud.com/)
+- [Germin8](http://www.germin8.com)
+- [GigaSpaces](http://www.gigaspaces.com)
+- [GMO Pepabo](https://pepabo.com/en/)
+- [goTransverse](http://www.gotransverse.com/api)
+- [GraphHopper](https://graphhopper.com/)
+- [Gravitate Solutions](http://gravitatesolutions.com/)
+- [HashData](http://www.hashdata.cn/)
+- [Hewlett Packard Enterprise](https://hpe.com)
+- [High Technologies Center](http://htc-cs.com)
+- [Hootsuite](https://hootsuite.com/)
+- [Huawei Cloud](http://www.huaweicloud.com/en-us/product/cs.html)
+- [Husbanken](https://www.husbanken.no)
+- [IBM](https://www.ibm.com)
+- [IMS Health](http://www.imshealth.com/en/solution-areas/technology-and-applications)
+- [Individual Standard IVS](http://www.individual-standard.com)
+- [INSPIDE](http://www.inspide.com)
+- [Intent HQ](http://www.intenthq.com)
+- [Kabuku](http://www.kabuku.co.jp/en)
+- [Kurio](https://kurio.co.id)
+- [Kuroi](http://kuroiwebdesign.com/)
+- [Kuary](https://kuary.com/)
+- [Kubernetes](https://kubernetes.io/)
+- [LANDR Audio](https://www.landr.com/)
+- [Lascaux](http://www.lascaux.it/)
+- [Leanix](http://www.leanix.net/)
+- [Leica Geosystems AG](http://leica-geosystems.com)
+- [LiveAgent](https://www.ladesk.com/)
+- [LXL Tech](http://lxltech.com)
+- [Lyft](https://www.lyft.com/developers)
+- [MailMojo](https://mailmojo.no/)
+- [Metaswitch](https://www.metaswitch.com/)
+- [Mindera](http://mindera.com/)
+- [ModuleQ](https://moduleq.com)
+- [Mporium](http://mporium.com/)
+- [Neverfail](https://neverfail.com/)
+- [NexCap](http://www.nexess-solutions.com/fr/plateforme-iot/)
+- [Nitrobox](https://www.nitrobox.com)
+- [Norwegian Air Shuttle](https://www.norwegian.com/)
+- [NTT DATA](http://www.nttdata.com/)
+- [nViso](http://www.nviso.ch/)
+- [NHSD](https://digital.nhs.uk/)
+- [Okiok](https://www.okiok.com)
+- [Onedata](http://onedata.org)
+- [Open International Systems](https://openintl.com/)
+- [OrderCloud.io](http://ordercloud.io)
+- [OSDN](https://osdn.jp)
+- [PagerDuty](https://www.pagerduty.com)
+- [PagerTree](https://pagertree.com)
+- [Pepipost](https://www.pepipost.com)
+- [Peatio Tech](https://www.peatio.tech)
+- [Plexxi](http://www.plexxi.com)
+- [Pixoneye](http://www.pixoneye.com/)
+- [PostAffiliatePro](https://www.postaffiliatepro.com/)
+- [PracticeBird](https://www.practicebird.com/)
+- [Prill Tecnologia](http://www.prill.com.br)
+- [Prokarma](https://www.prokarma.com)
+- [QAdept](http://qadept.com/)
+- [QuantiModo](https://quantimo.do/)
+- [QuickBlox](https://quickblox.com/)
+- [Rapid7](https://rapid7.com/)
+- [Red Hat](https://www.redhat.com/)
+- [Reload! A/S](https://reload.dk/)
+- [REstore](https://www.restore.eu)
+- [REST United](https://restunited.com)
+- [Revault Sàrl](http://revault.ch)
+- [Riffyn](https://riffyn.com)
+- [Roche](https://roche.com)
+- [Royal Bank of Canada (RBC)](http://www.rbc.com/canada.html)
+- [Saritasa](https://www.saritasa.com/)
+- [SAS](https://www.sas.com)
+- [SCOOP Software GmbH](http://www.scoop-software.de)
+- [SessionM](https://www.sessionm.com/)
+- [Shine Solutions](https://shinesolutions.com/)
+- [Simpfony](https://www.simpfony.com/)
+- [Skurt](http://www.skurt.com)
+- [Slamby](https://www.slamby.com/)
+- [SmartRecruiters](https://www.smartrecruiters.com/)
+- [snapCX](https://snapcx.io)
+- [SPINEN](http://www.spinen.com)
+- [Sponsoo](https://www.sponsoo.de)
+- [SRC](https://www.src.si/)
+- [Stardog Ventures](https://www.stardog.io)
+- [Stingray](http://www.stingray.com)
+- [StyleRecipe](http://stylerecipe.co.jp)
+- [Svenska Spel AB](https://www.svenskaspel.se/)
+- [Switch Database](https://www.switchdatabase.com/)
+- [TaskData](http://www.taskdata.com/)
+- [ThirdWatch.ai](https://www.thirdwatch.ai/)
+- [ThoughtWorks](https://www.thoughtworks.com)
+- [Tpay](https://tpay.com)
+- [Trexle](https://trexle.com/)
+- [Upwork](http://upwork.com/)
+- [uShip](https://www.uship.com/)
+- [Variograma](https://variograma.pt)
+- [VMware](https://vmware.com/)
+- [Viavi Solutions Inc.](https://www.viavisolutions.com)
+- [W.UP](http://wup.hu/?siteLang=en)
+- [Wealthfront](https://www.wealthfront.com/)
+- [Webever GmbH](https://www.webever.de/)
+- [WEXO A/S](https://www.wexo.dk/)
+- [XSky](http://www.xsky.com/)
+- [Yelp](http://www.yelp.com/)
+- [Zalando](https://tech.zalando.com)
+- [ZEEF.com](https://zeef.com/)
+- [zooplus](https://www.zooplus.com/)
+- [Trifork](https://www.trifork.com/)

docs/building.md

@@ -0,0 +1,92 @@
+# 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/master/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
+
+- https://hub.docker.com/r/swaggerapi/swagger-generator/ (official web service)
+- https://hub.docker.com/r/swaggerapi/swagger-codegen-cli/ (official CLI)
+
+### Swagger Generator Docker Image
+
+The Swagger Generator 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 at least two HTTP requests and some docker orchestration to access generated code.
+
+Example usage (note this assumes `jq` is installed for command line processing of JSON):
+
+```sh
+# Start container and save the container id
+CID=$(docker run -d swaggerapi/swagger-generator)
+# 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
+RESULT=$(curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
+  "swaggerUrl": "https://petstore.swagger.io/v2/swagger.json"
+}' 'http://localhost:8188/api/gen/clients/javascript' | jq '.link' | tr -d '"')
+# Download the generated zip and redirect to a file
+curl $RESULT > result.zip
+# Shutdown the swagger generator image
+docker stop $CID && docker rm $CID
+```
+
+In the example above, `result.zip` will contain the generated client.
+
+### 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 generate \
+    -i https://petstore.swagger.io/v2/swagger.json \
+    -l go \
+    -o /local/out/go
+```
+
+(On Windows replace `${PWD}` with `%CD%`)
+
+The generated code will be located under `./out/go` in the current directory.

docs/compatibility.md

@@ -0,0 +1,51 @@
+# 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.