diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000000..664eefdb4ee --- /dev/null +++ b/.dockerignore @@ -0,0 +1,26 @@ +.git/ +*.iml +out/ +*.ipr +*.iws +classpath.txt +version.properties +.project +.classpath +lib/* +build/* +generated-files/* +generated-sources/* +generated-code/* +*.swp +*.swo +*.bak +project/ +samples/* +target/ +.idea/ +.lib/ +.DS_Store + +# Not needed in a linux container +bin/windows/* diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 00000000000..277a7741fab --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,46 @@ + + +##### Description + + + +##### Swagger-codegen version + + + +##### Swagger declaration file content or url + + + +##### Command line used for generation + + + +##### Steps to reproduce + + + +##### Related issues + + + +##### Suggest a Fix + + + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000000..85641dcbae5 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,10 @@ +### PR checklist + +- [ ] Read the [contribution guidelines](https://github.com/swagger-api/swagger-codegen/blob/master/CONTRIBUTING.md). +- [ ] Ran the shell/batch script under `./bin/` to update Petstore sample so that CIs can verify the change. (For instance, only need to run `./bin/{LANG}-petstore.sh` and `./bin/security/{LANG}-petstore.sh` if updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates) +- [ ] Filed the PR against the correct branch: master for non-breaking changes and `2.3.0` branch for breaking (non-backward compatible) changes. + +### Description of the PR + +(details of the change, additional tests that have been done, reference to the issue for tracking, etc) + diff --git a/.gitignore b/.gitignore index b17bf46aa10..370da9c3256 100644 --- a/.gitignore +++ b/.gitignore @@ -4,27 +4,148 @@ out/ *.iws classpath.txt version.properties +!modules/swagger-codegen-cli/src/main/resources/version.properties .project .classpath lib/* build/* generated-files/* +generated-sources/* generated-code/* *.swp *.swo +target +.idea +.lib +atlassian-ide-plugin.xml +.DS_Store +packages/ +.pub +.packages +.vagrant/ + +.settings + +*.mustache~ +*.java~ +*.pm~ +*.xml~ +*.t~ /target /generated-files -/nbactions.xml -*.pyc -__pycache__ +nbactions.xml + +# scalatra samples/server-generator/scalatra/output -samples/server-generator/node/output/node_modules samples/server-generator/scalatra/target samples/server-generator/scalatra/output/.history -target -.idea -.lib -atlassian-ide-plugin.xml -.DS_Store +# nodejs +**/node_modules +samples/server-generator/node/output/node_modules +samples/server/petstore/nodejs/node_modules +samples/server/petstore/nodejs-server/node_modules + +# qt5 cpp +samples/client/petstore/qt5cpp/PetStore/moc_* +samples/client/petstore/qt5cpp/PetStore/*.o +samples/client/petstore/qt5cpp/build-* +samples/client/petstore/qt5cpp/PetStore/PetStore +samples/client/petstore/qt5cpp/PetStore/Makefile +samples/client/petstore/qt5cpp/PetStore/PetStore.pro.user + +#Java/Android +**/.gradle +samples/client/petstore/java/hello.txt +samples/client/petstore/java/okhttp-gson/hello.txt +samples/client/petstore/java/jersey1/hello.txt +samples/client/petstore/java/jersey2-java8/hello.txt +samples/client/petstore/android/default/hello.txt +samples/client/petstore/android/volley/.gradle/ +samples/client/petstore/android/volley/build/ +samples/client/petstore/java/jersey2/.gradle/ +samples/client/petstore/java/jersey2/build/ +samples/client/petstore/java/okhttp-gson/.gradle/ +samples/client/petstore/java/okhttp-gson/build/ +samples/client/petstore/java/feign/build/ +samples/client/petstore/java/retrofit/build/ +samples/client/petstore/java/retrofit2/build/ +samples/client/petstore/java/retrofit2rx/build/ +samples/client/petstore/java/default/build/ +samples/client/petstore/scala/build/ + +#PHP +samples/client/petstore/php/SwaggerClient-php/composer.lock +samples/client/petstore/php/SwaggerClient-php/vendor/ +samples/client/petstore/silex/SwaggerServer/composer.lock +samples/client/petstore/silex/SwaggerServer/venodr/ +**/vendor/ +**/composer.lock + +# Perl +samples/client/petstore/perl/deep_module_test/ + +# Objc +samples/client/petstore/objc/default/SwaggerClientTests/SwaggerClient.xcodeproj/xcuserdata +samples/client/petstore/objc/default/SwaggerClientTests/Build +samples/client/petstore/objc/default/SwaggerClientTests/Pods +samples/client/petstore/objc/default/SwaggerClientTests/SwaggerClient.xcworkspace +samples/client/petstore/objc/default/SwaggerClientTests/Podfile.lock + +samples/client/petstore/objc/core-data/SwaggerClientTests/SwaggerClient.xcodeproj/xcuserdata +samples/client/petstore/objc/core-data/SwaggerClientTests/Build +samples/client/petstore/objc/core-data/SwaggerClientTests/Pods +samples/client/petstore/objc/core-data/SwaggerClientTests/SwaggerClient.xcworkspace +samples/client/petstore/objc/core-data/SwaggerClientTests/Podfile.lock + +# Swift +samples/client/petstore/swift/SwaggerClientTests/SwaggerClient.xcodeproj/xcuserdata +samples/client/petstore/swift/SwaggerClientTests/SwaggerClient.xcworkspace/xcuserdata +samples/client/petstore/swift/SwaggerClientTests/Pods/Pods.xcodeproj/xcuserdata +samples/client/petstore/swift/SwaggerClientTests/Pods/Pods.xcodeproj/xcshareddata/xcschemes +samples/client/petstore/swift/**/SwaggerClientTests/Podfile.lock + +# C# +*.csproj.user +samples/client/petstore/csharp/SwaggerClient/IO.Swagger.userprefs +samples/client/petstore/csharp/SwaggerClientTest/.vs +samples/client/petstore/csharp/SwaggerClientTest/obj +samples/client/petstore/csharp/SwaggerClientTest/bin +samples/client/petstore/csharp/SwaggerClientTest/packages +samples/client/petstore/csharp/SwaggerClientTest/bin/Debug/ +samples/client/petstore/csharp/SwaggerClientTest/obj/Debug/ +samples/client/petstore/csharp/SwaggerClientTest/TestResult.xml +samples/client/petstore/csharp/SwaggerClientTest/nuget.exe +samples/client/petstore/csharp/SwaggerClientTest/testrunner/ +samples/client/petstore/csharp/SwaggerClient/.vs +samples/client/petstore/csharp/SwaggerClient/nuget.exe +samples/client/petstore/csharp/SwaggerClient/obj +samples/client/petstore/csharp/SwaggerClient/bin +samples/client/petstore/csharp/SwaggerClient/obj/Debug/ +samples/client/petstore/csharp/SwaggerClient/bin/Debug/ +samples/client/petstore/csharp/SwaggerClient/packages +samples/client/petstore/csharp/SwaggerClient/TestResult.xml +samples/client/petstore/csharp/SwaggerClientWithPropertyChanged/IO.Swagger.userprefs + +# Python +*.pyc +__pycache__ +samples/client/petstore/python/dev-requirements.txt.log +samples/client/petstore/python/swagger_client.egg-info/SOURCES.txt +samples/client/petstore/python/.coverage +samples/client/petstore/python/.projectile +samples/client/petstore/python/.venv/ + +# ts +samples/client/petstore/typescript-node/npm/node_modules +samples/client/petstore/typescript-node/**/typings +samples/client/petstore/typescript-angular/**/typings +samples/client/petstore/typescript-fetch/**/dist/ +samples/client/petstore/typescript-fetch/**/typings +samples/client/petstore/typescript-angular2/npm/npm-debug.log +samples/client/petstore/typescript-node/npm/npm-debug.log + +# aspnetcore +samples/server/petstore/aspnetcore/.vs/ + diff --git a/.travis.objc_swift_test.yml b/.travis.objc_swift_test.yml new file mode 100644 index 00000000000..8f7cf3b922d --- /dev/null +++ b/.travis.objc_swift_test.yml @@ -0,0 +1,57 @@ +sudo: required +language: objective-c +osx_image: xcode7.3 + +cache: + directories: + - $HOME/.m2 + - $HOME/.gem + - $HOME/.rvm + - $HOME/.cocoapods + - swagger-api/swagger-codegen/samples/client/petstore/objc/default/SwaggerClientTests/Pods + - swagger-api/swagger-codegen/samples/client/petstore/objc/core-data/SwaggerClientTests/Pods + - swagger-api/swagger-codegen/samples/client/petstore/swift/default/SwaggerClientTests/Pods + - swagger-api/swagger-codegen/samples/client/petstore/swift/promisekit/SwaggerClientTests/Pods + +services: + - docker + +addons: + hosts: + - petstore.swagger.io + +before_install: + - export SW=`pwd` + # show host table to confirm petstore.swagger.io is mapped to localhost + - cat /private/etc/hosts + #- rvm install 2.2.2 > /dev/null 2>&1 + - rvm use 2.2.4 + - gem environment + - gem install cocoapods -v 1.0.1 -N --no-ri --no-rdoc + - gem install xcpretty -N --no-ri --no-rdoc + - pod --version + - pod setup --silent > /dev/null + # xctool already pre-installed + #- brew install xctool + - git clone https://github.com/wing328/swagger-samples + - cd swagger-samples/java/java-jersey-jaxrs && sudo mvn -q jetty:run & + +install: + +script: + # test default objc client + - cd $SW/samples/client/petstore/objc/default/SwaggerClientTests && pod install && xctool -workspace "SwaggerClient.xcworkspace" -scheme "SwaggerClient-Example" -destination platform='iOS Simulator',OS=8.4,name='iPhone 6' test -test-sdk iphonesimulator CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO + # test objc client with coredata + - cd $SW/samples/client/petstore/objc/core-data/SwaggerClientTests && pod install && xctool -workspace "SwaggerClient.xcworkspace" -scheme "SwaggerClient-Example" -destination platform='iOS Simulator',OS=8.4,name='iPhone 6' test -test-sdk iphonesimulator CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO + - set -o pipefail + # test swift client with promisekit + - cd $SW/samples/client/petstore/swift/promisekit/SwaggerClientTests && pod install && xcodebuild clean test -workspace "SwaggerClient.xcworkspace" -scheme "SwaggerClient" -sdk iphonesimulator GCC_INSTRUMENT_PROGRAM_FLOW_ARCS=YES GCC_GENERATE_TEST_COVERAGE_FILES=YES | xcpretty + # test default swift client + - cd $SW/samples/client/petstore/swift/default/SwaggerClientTests && pod install && xcodebuild clean test -workspace "SwaggerClient.xcworkspace" -scheme "SwaggerClient" -sdk iphonesimulator GCC_INSTRUMENT_PROGRAM_FLOW_ARCS=YES GCC_GENERATE_TEST_COVERAGE_FILES=YES | xcpretty + # test swift3 client with promisekit + - cd $SW/samples/client/petstore/swift3/promisekit/SwaggerClientTests && pod install && xcodebuild clean test -workspace "SwaggerClient.xcworkspace" -scheme "SwaggerClient" -sdk iphonesimulator GCC_INSTRUMENT_PROGRAM_FLOW_ARCS=YES GCC_GENERATE_TEST_COVERAGE_FILES=YES | xcpretty + # test default swift3 client + - cd $SW/samples/client/petstore/swift3/default/SwaggerClientTests && pod install && xcodebuild clean test -workspace "SwaggerClient.xcworkspace" -scheme "SwaggerClient" -sdk iphonesimulator GCC_INSTRUMENT_PROGRAM_FLOW_ARCS=YES GCC_GENERATE_TEST_COVERAGE_FILES=YES | xcpretty + +env: + - DOCKER_IMAGE_NAME=swaggerapi/swagger-generator diff --git a/.travis.yml b/.travis.yml index 85a33a2d847..67273567000 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,4 +1,77 @@ +sudo: required language: java -script: mvn verify jdk: - oraclejdk7 + - oraclejdk8 + +cache: + directories: + - $HOME/.m2 + - $HOME/.ivy2 + - $HOME/.gradle/caches/ + - $HOME/.gradle/wrapper/ + - $HOME/samples/client/petstore/php/SwaggerClient-php/vendor + - $HOME/samples/client/petstore/ruby/venodr/bundle + - $HOME/samples/client/petstore/python/.venv/ + - $HOME/samples/client/petstore/typescript-node/npm/node_modules + - $HOME/samples/client/petstore/typescript-node/npm/typings/ + - $HOME/samples/client/petstore/typescript-fetch/tests/default/node_modules + - $HOME/samples/client/petstore/typescript-fetch/tests/default/typings + - $HOME/samples/client/petstore/typescript-fetch/builds/default/node_modules + - $HOME/samples/client/petstore/typescript-fetch/builds/default/typings + - $HOME/samples/client/petstore/typescript-fetch/builds/es6-target/node_modules + - $HOME/samples/client/petstore/typescript-fetch/builds/es6-target/typings + - $HOME/samples/client/petstore/typescript-fetch/builds/with-npm-version/node_modules + - $HOME/samples/client/petstore/typescript-fetch/npm/with-npm-version/typings + - $HOME/samples/client/petstore/typescript-angular/node_modules + - $HOME/samples/client/petstore/typescript-angular/typings + +services: + - docker + +addons: + hosts: + - petstore.swagger.io + +before_install: + # required when sudo: required for the Ruby petstore tests + - gem install bundler + - npm install -g typescript + - sudo pip install virtualenv + # to run petstore server locally via docker + - docker pull swaggerapi/petstore + - docker run -d -e SWAGGER_HOST=http://petstore.swagger.io -e SWAGGER_BASE_PATH=/v2 -p 80:8080 swaggerapi/petstore + - docker ps -a + # Add bats test framework and cURL for Bash script integration tests + - sudo add-apt-repository ppa:duggan/bats --yes + - sudo apt-get update -qq + - sudo apt-get install -qq bats + - sudo apt-get install -qq curl + + # show host table to confirm petstore.swagger.io is mapped to localhost + - cat /etc/hosts + # show java version + - java -version + +install: + # Add Godeps dependencies to GOPATH and PATH + - eval "$(curl -sL https://raw.githubusercontent.com/travis-ci/gimme/master/gimme | GIMME_GO_VERSION=1.4 bash)" + - export GOPATH="${TRAVIS_BUILD_DIR}/Godeps/_workspace" + - export PATH="${TRAVIS_BUILD_DIR}/Godeps/_workspace/bin:$PATH" + +script: + # fail fast + - set -e + # fail if templates/generators contain carriage return '\r' + - /bin/bash ./bin/utils/detect_carriage_return.sh + # fail if generators contain tab '\t' + - /bin/bash ./bin/utils/detect_tab_in_java_class.sh + # run integration tests defined in maven pom.xml + - mvn --batch-mode verify -Psamples + # docker: build generator image and push to Docker Hub + - if [ $DOCKER_HUB_USERNAME ]; then docker login --email=$DOCKER_HUB_EMAIL --username=$DOCKER_HUB_USERNAME --password=$DOCKER_HUB_PASSWORD && docker build -t $DOCKER_GENERATOR_IMAGE_NAME ./modules/swagger-generator && if [ ! -z "$TRAVIS_TAG" ]; then docker tag $DOCKER_GENERATOR_IMAGE_NAME:latest $DOCKER_GENERATOR_IMAGE_NAME:$TRAVIS_TAG; fi && if [ ! -z "$TRAVIS_TAG" ] || [ "$TRAVIS_BRANCH" = "master" ]; then docker push $DOCKER_GENERATOR_IMAGE_NAME; fi; fi + # docker: build cli image and push to Docker Hub + - if [ $DOCKER_HUB_USERNAME ]; then docker login --email=$DOCKER_HUB_EMAIL --username=$DOCKER_HUB_USERNAME --password=$DOCKER_HUB_PASSWORD && docker build -t $DOCKER_CODEGEN_CLI_IMAGE_NAME ./modules/swagger-codegen-cli && if [ ! -z "$TRAVIS_TAG" ]; then docker tag $DOCKER_CODEGEN_CLI_IMAGE_NAME:latest $DOCKER_CODEGEN_CLI_IMAGE_NAME:$TRAVIS_TAG; fi && if [ ! -z "$TRAVIS_TAG" ] || [ "$TRAVIS_BRANCH" = "master" ]; then docker push $DOCKER_CODEGEN_CLI_IMAGE_NAME; fi; fi + +env: + - DOCKER_GENERATOR_IMAGE_NAME=swaggerapi/swagger-generator DOCKER_CODEGEN_CLI_IMAGE_NAME=swaggerapi/swagger-codegen-cli diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..2d56048159f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,82 @@ +# Guidelines For Contributing + +## Before submitting an issue + + - If you're not using the latest master to generate API clients or server stubs, please give it another try by pulling the latest master as the issue may have already been addressed. Ref: [Getting Started](https://github.com/swagger-api/swagger-codegen#getting-started) + - Search the [open issue](https://github.com/swagger-api/swagger-codegen/issues) and [closed issue](https://github.com/swagger-api/swagger-codegen/issues?q=is%3Aissue+is%3Aclosed) to ensure no one else has reported something similar before. + - File an [issue ticket](https://github.com/swagger-api/swagger-codegen/issues/new) by providing all the required information. + - Test with the latest master by building the JAR locally to see if the issue has already been addressed. + - You can also make a suggestion or ask a question by opening an "issue". + +## Before submitting a PR + + - Search the [open issue](https://github.com/swagger-api/swagger-codegen/issues) to ensure no one else has reported something similar and no one is actively working on similar proposed change. + - If no one has suggested something similar, open an ["issue"](https://github.com/swagger-api/swagger-codegen/issues) with your suggestion to gather feedback from the community. + - It's recommended to **create a new git branch** for the change so that the merge commit message looks nicer in the commit history. + +## How to contribute + +### Code generators + +All the code generators can be found in [modules/swagger-codegen/src/main/java/io/swagger/codegen/languages](https://github.com/swagger-api/swagger-codegen/tree/master/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages) + +### Templates + +All the templates ([mustache](https://mustache.github.io/)) can be found in [modules/swagger-codegen/src/main/resources](https://github.com/swagger-api/swagger-codegen/tree/master/modules/swagger-codegen/src/main/resources). + +For a list of variables available in the template, please refer to this [page](https://github.com/swagger-api/swagger-codegen/wiki/Mustache-Template-Variables) + + +### Style guide +Code change should conform to the programming style guide of the respective languages: +- Android: https://source.android.com/source/code-style.html +- Bash: https://github.com/bahamas10/bash-style-guide +- C#: https://msdn.microsoft.com/en-us/library/vstudio/ff926074.aspx +- C++: https://google.github.io/styleguide/cppguide.html +- Clojure: https://github.com/bbatsov/clojure-style-guide +- Elixir: https://github.com/christopheradams/elixir_style_guide +- Erlang: https://github.com/inaka/erlang_guidelines +- Haskell: https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md +- Java: https://google.github.io/styleguide/javaguide.html +- JavaScript: https://github.com/airbnb/javascript/ +- Groovy: http://groovy-lang.org/style-guide.html +- Go: https://github.com/golang/go/wiki/CodeReviewComments +- ObjC: https://github.com/NYTimes/objective-c-style-guide +- Perl: http://perldoc.perl.org/perlstyle.html +- PHP: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md +- Python: https://www.python.org/dev/peps/pep-0008/ +- Ruby: https://github.com/bbatsov/ruby-style-guide +- Scala: http://docs.scala-lang.org/style/ +- Swift: https://developer.apple.com/library/prerelease/ios/documentation/Swift/Conceptual/Swift_Programming_Language/TheBasics.html +- TypeScript: https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines + +For other languages, feel free to suggest. + +You may find the current code base not 100% conform to the coding style and we welcome contributions to fix those. + +For [Vendor Extensions](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#vendorExtensions), please follow the naming convention below: +- For general vendor extension, use lower case and hyphen. e.g. `x-is-unique`, `x-content-type` +- For language-specified vendor extension, put it in the form of `x-{lang}-{extension-name}`. e.g. `x-objc-operation-id`, `x-java-feign-retry-limit` +- For a list of existing vendor extensions in use, please refer to https://github.com/swagger-api/swagger-codegen/wiki/Vendor-Extensions. If you've added new vendor extensions as part of your PR, please update the wiki page. + +### Testing + +To add test cases (optional) covering the change in the code generator, please refer to [modules/swagger-codegen/src/test/java/io/swagger/codegen](https://github.com/swagger-api/swagger-codegen/tree/master/modules/swagger-codegen/src/test/java/io/swagger/codegen) + +To test the templates, please perform the following: +- Update the [Petstore](http://petstore.swagger.io/) sample by running the shell script under `bin` folder. For example, run `./bin/ruby-petstore.sh` to update the Ruby PetStore API client under [`samples/client/petstore/ruby`](https://github.com/swagger-api/swagger-codegen/tree/master/samples/client/petstore/ruby) For Windows, the batch files can be found under `bin\windows` folder. (If you find that there are new files generated or unexpected changes as a result of the update, that's not unusual as the test cases are added to the OpenAPI/Swagger spec from time to time. If you've questions or concerns, please open a ticket to start a discussion) +- Run the tests in the sample folder, e.g. in `samples/client/petstore/ruby`, run `mvn integration-test -rf :RubyPetstoreClientTests`. (some languages may not contain unit testing for Petstore and we're looking for contribution from the community to implement those tests) +- Finally, git commit the updated samples files: `git commit -a` + (`git add -A` if added files with new test cases) + +To start the CI tests, you can run `mvn verify -Psamples` (assuming you've all the required tools installed to run tests for different languages) or you can leverage http://travis-ci.org to run the CI tests by adding your own Swagger-Codegen repository. + +### Tips +- Smaller changes are easier to review +- [Optional] For bug fixes, provide a OpenAPI Spec to repeat the issue so that the reviewer can use it to confirm the fix +- Add test case(s) to cover the change +- Document the fix in the code to make the code more readable +- Make sure test cases passed after the change (one way is to leverage https://travis-ci.org/ to run the CI tests) +- File a PR with meaningful title, description and commit messages. A good example is [PR-3306](https://github.com/swagger-api/swagger-codegen/pull/3306) +- Recommended git settings + - `git config --global core.autocrlf input` to tell Git convert CRLF to LF on commit but not the other way around diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000000..ec291fef4af --- /dev/null +++ b/Dockerfile @@ -0,0 +1,22 @@ +FROM jimschubert/8-jdk-alpine-mvn:1.0 + +ENV GEN_DIR /opt/swagger-codegen + +RUN set -x && \ + apk add --no-cache bash + +RUN mkdir /opt + +ADD . ${GEN_DIR} + +VOLUME ${MAVEN_HOME}/.m2/repository + +WORKDIR ${GEN_DIR} + +RUN mvn -am -pl "modules/swagger-codegen-cli" package + +COPY docker-entrypoint.sh /usr/local/bin/ + +ENTRYPOINT ["docker-entrypoint.sh"] + +CMD ["build"] diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000000..ebfd64c4931 --- /dev/null +++ b/LICENSE @@ -0,0 +1,11 @@ +Copyright 2016 SmartBear Software + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at [apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/README.md b/README.md index 321de9c795a..2c50675b5c7 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,366 @@ # Swagger Code Generator -[![Build Status](https://travis-ci.org/swagger-api/swagger-codegen.png)](https://travis-ci.org/swagger-api/swagger-codegen) +[![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 client libraries automatically from a Swagger-compliant server. +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 (**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 | 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 | 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) -## What's Swagger? -The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, Swagger removes the guesswork in calling the service. +### 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 -Check out [Swagger-Spec](https://github.com/swagger-api/swagger-spec) for additional information about the Swagger project, including additional libraries with support for other languages and more. +java -jar swagger-codegen-cli.jar help +``` +On a mac, it's even easier with `brew`: +``` +brew install swagger-codegen +``` -## Compatability -The Swagger Specification has undergone 3 revisions since initial creation in 2010. The swagger-codegen project has the following compatibilies with the swagger specification: +To build from source, you need the following installed and available in your $PATH: -Swagger Codegen Version | Release Date | Swagger Spec compatability | Notes ------------------------ | ------------ | -------------------------- | ----- -2.1.0-M1 | 2015-02-16 | 1.0, 1.1, 1.2, 2.0 | [tag v2.1.0-M1](https://github.com/swagger-api/swagger-codegen/tree/v2.1.0-M1) -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) +* [Java 7 or 8](http://java.oracle.com) +* [Apache maven 3.3.3 or greater](http://maven.apache.org/) -### Prerequisites -You need the following installed and available in your $PATH: +#### OS X Users +Don't forget to install Java 7 or 8. You probably have 1.6. -* [Java 7](http://java.oracle.com) +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 +``` -* [Apache maven 3.0.3 or greater](http://maven.apache.org/) +### 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: ``` -mvn package +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 Wordnik's [petstore](http://petstore.swagger.io) API as follows: +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-distribution/target/swagger-codegen-distribution-2.1.0-M1.jar \ +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 -h flag: -``` -usage: Codegen - -a,--auth addes authorization headers when fetching the - swagger definitions remotely. Pass in a - URL-encoded string of name:header with a comma - separating multiple values - -d,--debug-info prints additional info for debugging - -h,--help shows this message - -i,--input-spec location of the swagger spec, as URL or file - -l,--lang client language to generate. - Available languages include: - [android, java, jaxrs, nodejs, objc, scalatra, - scala, dynamic-html, html, swagger, tizen, php, - python] - -o,--output where to write the generated files - -t,--template-dir folder containing the template files - ``` +with a number of options. You can get the options with the `help generate` command: + +``` +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