diff --git a/README.md b/README.md index 1457eb62ba1..d0d14f1a2c0 100644 --- a/README.md +++ b/README.md @@ -1,982 +1,32 @@ -# Swagger Code Generator - -[![Build Status](https://img.shields.io/travis/swagger-api/swagger-codegen/master.svg?label=Petstore%20Integration%20Test)](https://travis-ci.org/swagger-api/swagger-codegen) -[![Run Status](https://img.shields.io/shippable/5782588a3be4f4faa56c5bea.svg?label=Mustache%20Template%20Test)](https://app.shippable.com/projects/5782588a3be4f4faa56c5bea) -[![Windows Test](https://ci.appveyor.com/api/projects/status/github/swagger-api/swagger-codegen?branch=master&svg=true&passingText=Windows%20Test%20-%20OK&failingText=Windows%20Test%20-%20Fails)](https://ci.appveyor.com/project/WilliamCheng/swagger-codegen-wh2wu) -[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.swagger/swagger-codegen-project/badge.svg?style=plastic)](https://maven-badges.herokuapp.com/maven-central/io.swagger/swagger-codegen-project) -[![PR Stats](http://issuestats.com/github/swagger-api/swagger-codegen/badge/pr)](http://issuestats.com/github/swagger-api/swagger-codegen) [![Issue Stats](http://issuestats.com/github/swagger-api/swagger-codegen/badge/issue)](http://issuestats.com/github/swagger-api/swagger-codegen) - -:star::star::star: If you would like to contribute, please refer to [guidelines](https://github.com/swagger-api/swagger-codegen/blob/master/CONTRIBUTING.md) and a list of [open tasks](https://github.com/swagger-api/swagger-codegen/issues?q=is%3Aopen+is%3Aissue+label%3A%22Need+community+contribution%22).:star::star::star: - -:notebook_with_decorative_cover: For more information, please refer to the [Wiki page](https://github.com/swagger-api/swagger-codegen/wiki) and [FAQ](https://github.com/swagger-api/swagger-codegen/wiki/FAQ) :notebook_with_decorative_cover: - -:warning: If the OpenAPI/Swagger spec is obtained from an untrusted source, please make sure you've reviewed the spec before using Swagger Codegen to generate the API client, server stub or documentation as [code injection](https://en.wikipedia.org/wiki/Code_injection) may occur :warning: - -:rocket: ProductHunt: https://producthunt.com/posts/swagger-codegen :rocket: - -## Overview -This is the swagger codegen project, which allows generation of API client libraries (SDK generation), server stubs and documentation automatically given an [OpenAPI Spec](https://github.com/OAI/OpenAPI-Specification). Currently, the following languages/frameworks are supported: - -- **API clients**: **ActionScript**, **Bash**, **C#** (.net 2.0, 4.0 or later), **C++** (cpprest, Qt5, Tizen), **Clojure**, **Dart**, **Elixir**, **Go**, **Groovy**, **Haskell**, **Java** (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign), **Node.js** (ES5, ES6, AngularJS with Google Closure Compiler annotations) **Objective-C**, **Perl**, **PHP**, **Python**, **Ruby**, **Scala**, **Swift** (2.x, 3.x), **Typescript** (Angular1.x, Angular2.x, Fetch, jQuery, Node) -- **Server stubs**: **C#** (ASP.NET Core, NancyFx), **Erlang**, **Go**, **Haskell**, **Java** (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy), **PHP** (Lumen, Slim, Silex, [Zend Expressive](https://github.com/zendframework/zend-expressive)), **Python** (Flask), **NodeJS**, **Ruby** (Sinatra, Rails5), **Scala** ([Finch](https://github.com/finagle/finch), Scalatra) -- **API documentation generators**: **HTML**, **Confluence Wiki** -- **Others**: **JMeter** - -Check out [OpenAPI-Spec](https://github.com/OAI/OpenAPI-Specification) for additional information about the OpenAPI project. - -# Table of contents - - - [Swagger Code Generator](#swagger-code-generator) - - [Overview](#overview) - - [Table of Contents](#table-of-contents) - - Installation - - [Compatibility](#compatibility) - - [Prerequisites](#prerequisites) - - [OS X Users](#os-x-users) - - [Building](#building) - - [Docker](#docker) - - [Build and run](#build-and-run-using-docker) - - [Run docker in Vagrant](#run-docker-in-vagrant) - - [Public Docker image](#public-docker-image) - - [Homebrew](#homebrew) - - [Getting Started](#getting-started) - - Generators - - [To generate a sample client library](#to-generate-a-sample-client-library) - - [Generating libraries from your server](#generating-libraries-from-your-server) - - [Modifying the client library format](#modifying-the-client-library-format) - - [Making your own codegen modules](#making-your-own-codegen-modules) - - [Where is Javascript???](#where-is-javascript) - - [Generating a client from local files](#generating-a-client-from-local-files) - - [Customizing the generator](#customizing-the-generator) - - [Validating your OpenAPI Spec](#validating-your-openapi-spec) - - [Generating dynamic html api documentation](#generating-dynamic-html-api-documentation) - - [Generating static html api documentation](#generating-static-html-api-documentation) - - [To build a server stub](#to-build-a-server-stub) - - [To build the codegen library](#to-build-the-codegen-library) - - [Workflow Integration](#workflow-integration) - - [Github Integration](#github-integration) - - [Online Generators](#online-generators) - - [Guidelines for Contribution](https://github.com/swagger-api/swagger-codegen/wiki/Guidelines-for-Contribution) - - [Companies/Projects using Swagger Codegen](#companiesprojects-using-swagger-codegen) - - [Swagger Codegen Core Team](#swagger-codegen-core-team) - - [Swagger Codegen Evangelist](#swagger-codegen-evangelist) - - [License](#license) - - -## Compatibility -The OpenAPI Specification has undergone 3 revisions since initial creation in 2010. The swagger-codegen project has the following compatibilities with the OpenAPI Specification: - -Swagger Codegen Version | Release Date | OpenAPI Spec compatibility | Notes --------------------------- | ------------ | -------------------------- | ----- -2.3.0 (upcoming minor release) | Apr/May 2017 | 1.0, 1.1, 1.2, 2.0 | Minor release with breaking changes -2.2.3 (upcoming patch release) | TBD | 1.0, 1.1, 1.2, 2.0 | Patch release without breaking changes -[2.2.2](https://github.com/swagger-api/swagger-codegen/releases/tag/v2.2.2) (**current stable**) | 2017-03-01 | 1.0, 1.1, 1.2, 2.0 | [tag v2.2.2](https://github.com/swagger-api/swagger-codegen/tree/v2.2.2) -[2.2.1](https://github.com/swagger-api/swagger-codegen/releases/tag/v2.2.1) | 2016-08-07 | 1.0, 1.1, 1.2, 2.0 | [tag v2.2.1](https://github.com/swagger-api/swagger-codegen/tree/v2.2.1) -[2.1.6](https://github.com/swagger-api/swagger-codegen/releases/tag/v2.1.6) | 2016-04-06 | 1.0, 1.1, 1.2, 2.0 | [tag v2.1.6](https://github.com/swagger-api/swagger-codegen/tree/v2.1.6) -2.0.17 | 2014-08-22 | 1.1, 1.2 | [tag v2.0.17](https://github.com/swagger-api/swagger-codegen/tree/v2.0.17) -1.0.4 | 2012-04-12 | 1.0, 1.1 | [tag v1.0.4](https://github.com/swagger-api/swagger-codegen/tree/swagger-codegen_2.9.1-1.1) - - -### Prerequisites -If you're looking for the latest stable version, you can grab it directly from Maven.org (Java 7 runtime at a minimum): - -``` -wget http://central.maven.org/maven2/io/swagger/swagger-codegen-cli/2.2.2/swagger-codegen-cli-2.2.2.jar -O swagger-codegen-cli.jar - -java -jar swagger-codegen-cli.jar help -``` - -On a mac, it's even easier with `brew`: -``` -brew install swagger-codegen -``` - -To build from source, you need the following installed and available in your $PATH: - -* [Java 7 or 8](http://java.oracle.com) - -* [Apache maven 3.3.3 or greater](http://maven.apache.org/) - -#### OS X Users -Don't forget to install Java 7 or 8. You probably have 1.6. - -Export JAVA_HOME in order to use the supported Java version: -``` -export JAVA_HOME=`/usr/libexec/java_home -v 1.8` -export PATH=${JAVA_HOME}/bin:$PATH -``` - -### Building - -After cloning the project, you can build it from source with this command: -``` -mvn clean package -``` - -### Homebrew - -To install, run `brew install swagger-codegen` - -Here is an example usage: -``` -swagger-codegen generate -i http://petstore.swagger.io/v2/swagger.json -l ruby -o /tmp/test/ -``` - -### 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`: - -``` -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: - -``` -./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 -``` - -#### Run Docker in Vagrant -Prerequisite: install [Vagrant](https://www.vagrantup.com/downloads.html) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads). - ``` -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): - -``` -# 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": "http://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: - -``` -docker run --rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli 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. - -## Getting Started - -To generate a PHP client for http://petstore.swagger.io/v2/swagger.json, please run the following -```sh -git clone https://github.com/swagger-api/swagger-codegen -cd swagger-codegen -mvn clean package -java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \ - -i http://petstore.swagger.io/v2/swagger.json \ - -l php \ - -o /var/tmp/php_api_client -``` -(if you're on Windows, replace the last command with `java -jar modules\swagger-codegen-cli\target\swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l php -o c:\temp\php_api_client`) - -You can also download the JAR (latest release) directly from [maven.org](http://central.maven.org/maven2/io/swagger/swagger-codegen-cli/2.2.2/swagger-codegen-cli-2.2.2.jar) - -To get a list of **general** options available, please run `java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar help generate` - -To get a list of PHP specified options (which can be passed to the generator with a config file via the `-c` option), please run `java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php` - -## Generators - -### To generate a sample client library -You can build a client against the swagger sample [petstore](http://petstore.swagger.io) API as follows: - -``` -./bin/java-petstore.sh -``` - -(On Windows, run `.\bin\windows\java-petstore.bat` instead) - -This will run the generator with this command: - -``` -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 -``` - -with a number of options. You can get the options with the `help generate` command (below only shows partal results): - -``` -NAME - swagger-codegen-cli generate - Generate code with chosen lang - -SYNOPSIS - swagger-codegen-cli generate - [(-a | --auth )] - [--additional-properties ] - [--api-package ] [--artifact-id ] - [--artifact-version ] - [(-c | --config )] - [-D ] [--group-id ] - (-i | --input-spec ) - [--import-mappings ] - [--instantiation-types ] - [--invoker-package ] - (-l | --lang ) - [--language-specific-primitives ] - [--library ] [--model-package ] - [(-o | --output )] - [(-s | --skip-overwrite)] - [(-t