diff --git a/.dockerignore b/.dockerignore index a0e39ffd165c..75ea5de6ca2f 100644 --- a/.dockerignore +++ b/.dockerignore @@ -30,7 +30,7 @@ samples/client/petstore/qt5cpp/build-* samples/client/petstore/qt5cpp/PetStore/PetStore samples/client/petstore/qt5cpp/PetStore/Makefile samples/client/petstore/java/hello.txt -samples/client/petstore/android-java/hello.txt +samples/client/petstore/android/default/hello.txt samples/client/petstore/objc/Build samples/client/petstore/objc/Pods samples/server/petstore/nodejs/node_modules diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 000000000000..9a56dca7f029 --- /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/.gitignore b/.gitignore index 02ecb7220cdf..adea0e97125a 100644 --- a/.gitignore +++ b/.gitignore @@ -13,33 +13,6 @@ generated-sources/* generated-code/* *.swp *.swo -*.csproj.user - -/target -/generated-files -/nbactions.xml -*.pyc -__pycache__ -samples/server-generator/scalatra/output -samples/server-generator/node/output/node_modules -samples/server-generator/scalatra/target -samples/server-generator/scalatra/output/.history -samples/client/petstore/qt5cpp/PetStore/moc_* -samples/client/petstore/qt5cpp/PetStore/*.o -samples/client/petstore/objc/PetstoreClient.xcworkspace/xcuserdata -samples/client/petstore/qt5cpp/build-* -samples/client/petstore/qt5cpp/PetStore/PetStore -samples/client/petstore/qt5cpp/PetStore/Makefile -samples/client/petstore/java/hello.txt -samples/client/petstore/android-java/hello.txt -samples/client/petstore/objc/SwaggerClientTests/Build -samples/client/petstore/objc/SwaggerClientTests/Pods -samples/client/petstore/objc/SwaggerClientTests/SwaggerClient.xcworkspace -samples/client/petstore/objc/SwaggerClientTests/Podfile.lock -samples/server/petstore/nodejs/node_modules -samples/client/petstore/csharp/SwaggerClientTest/.vs -samples/client/petstore/csharp/SwaggerClientTest/obj -samples/client/petstore/csharp/SwaggerClientTest/bin target .idea .lib @@ -48,15 +21,7 @@ atlassian-ide-plugin.xml packages/ .pub .packages - -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/ - -samples/client/petstore/python/.projectile -samples/client/petstore/python/.venv/ +.vagrant/ .settings @@ -65,3 +30,113 @@ samples/client/petstore/python/.venv/ *.pm~ *.xml~ *.t~ + +/target +/generated-files +/nbactions.xml + +# scalatra +samples/server-generator/scalatra/output +samples/server-generator/scalatra/target +samples/server-generator/scalatra/output/.history + +# 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 + +#Java/Android +**/.gradle +samples/client/petstore/java/hello.txt +samples/client/petstore/java/okhttp-gson/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 + +# 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 + diff --git a/.travis.yml b/.travis.yml index 73dc7fdd26df..1a62cea31613 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,5 +1,41 @@ -sudo: false +sudo: required language: java -script: mvn verify -Psamples jdk: - oraclejdk7 + - oraclejdk8 + +cache: + directories: + - $HOME/.m2 + +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 + # show host table to confirm petstore.swagger.io is mapped to localhost + - cat /etc/hosts + +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: + - mvn verify -Psamples + - if [ $DOCKER_HUB_USERNAME ]; then docker login --email=$DOCKER_HUB_EMAIL --username=$DOCKER_HUB_USERNAME --password=$DOCKER_HUB_PASSWORD && docker build -t $DOCKER_IMAGE_NAME ./modules/swagger-generator && if [ ! -z "$TRAVIS_TAG" ]; then docker tag $DOCKER_IMAGE_NAME:latest $DOCKER_IMAGE_NAME:$TRAVIS_TAG; fi && docker push $DOCKER_IMAGE_NAME; fi + +env: + - DOCKER_IMAGE_NAME=swaggerapi/swagger-generator diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4bef580bb265..2551c58bc6db 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,17 +2,16 @@ ## Before submitting an issue - - Before submitting an issue, 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. - - The issue should contain details on how to repeat the issue, e.g. - - the Swagger spec for reproducing the issue (:bulb: use [Gist](https://gist.github.com) to share). If the Swagger spec cannot be shared publicly, it will be hard for the community to help - - version of Swagger Codegen - - language (`-l` in the command line, e.g. java, csharp, php) - - You can also make a suggestion or ask a question by opening 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. + - 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 @@ -29,25 +28,38 @@ For a list of variables available in the template, please refer to this [page](h ### Style guide Code change should conform to the programming style guide of the respective langauages: +- Android: https://source.android.com/source/code-style.html - C#: https://msdn.microsoft.com/en-us/library/vstudio/ff926074.aspx +- C++: https://google.github.io/styleguide/cppguide.html +- 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/tree/master/es5 +- 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 addaed 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) +- 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) @@ -56,7 +68,7 @@ To start the CI tests, you can run `mvn verify -Psamples` (assuming you've all t ### Tips - Smaller changes are easier to review -- [Optional] For bug fixes, provide a Swagger spec to repeat the issue so that the reviewer can use it to confirm the fix +- [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) diff --git a/LICENSE b/LICENSE index 542991f95502..ebfd64c49317 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright 2015 SmartBear Software +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. diff --git a/README.md b/README.md index 3f1691144b9a..426bd761f31d 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,21 @@ # 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.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: -## Overview -This is the swagger codegen project, which allows generation of client libraries automatically from a Swagger-compliant server. +: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: -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. +: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: + +## Overview +This is the swagger codegen project, which allows generation of API client libraries, server stubs and documentation automatically given an [OpenAPI Spec](https://github.com/OAI/OpenAPI-Specification). + +Check out [Swagger-Spec](https://github.com/OAI/OpenAPI-Specification) for additional information about the Swagger project, including additional libraries with support for other languages and more. # Table of contents @@ -22,8 +29,10 @@ Check out [Swagger-Spec](https://github.com/swagger-api/swagger-spec) for additi - [Building](#building) - [Docker](#docker) - [Build and run](#build-and-run-using-docker) - - [Build a Node.js server stub](#build-a-nodejs-server-stub) + - [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) @@ -32,47 +41,59 @@ Check out [Swagger-Spec](https://github.com/swagger-api/swagger-spec) for additi - [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 swagger spec](#validating-your-swagger-spec) + - [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) - - [Node.js](#nodejs) - - [PHP Silex](#php-silex) - - [Python Flask (Connexion)](#python-flask-connexion) - - [Ruby Sinatra](#ruby-sinatra) - - [Scala Scalatra](#scala-scalatra) - - [Java JAX-RS](#java-jax-rs) - - [Java Spring MVC](#java-spring-mvc) - [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) - [License](#license) ## Compatibility -The Swagger Specification has undergone 3 revisions since initial creation in 2010. The swagger-codegen project has the following compatibilies with the swagger specification: +The OpenAPI Specification has undergone 3 revisions since initial creation in 2010. The swagger-codegen project has the following compatibilies with the OpenAPI Specification: -Swagger Codegen Version | Release Date | Swagger Spec compatibility | Notes +Swagger Codegen Version | Release Date | OpenAPI Spec compatibility | Notes -------------------------- | ------------ | -------------------------- | ----- -2.1.5-SNAPSHOT | | 1.0, 1.1, 1.2, 2.0 | [master](https://github.com/swagger-api/swagger-codegen) -2.1.4 (**current stable**) | 2015-10-25 | 1.0, 1.1, 1.2, 2.0 | [tag v2.1.4](https://github.com/swagger-api/swagger-codegen/tree/v2.1.4) +2.3.0 (upcoming minor release) | TBD | 1.0, 1.1, 1.2, 2.0 | Minor release with breaking changes +2.2.2 (upcoming patch release) | TBD | 1.0, 1.1, 1.2, 2.0 | Patch release (without breaking changes) +2.2.1 (**current stable**) | 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) ### Prerequisites -You need the following installed and available in your $PATH: +If you're looking for the latest stable version, you can grab it directly from maven central (you'll need java 7 runtime at a minimum): -* [Java 7](http://java.oracle.com) +``` +wget http://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.2.1/swagger-codegen-cli-2.2.1.jar -O swagger-codegen-cli.jar -* [Apache maven 3.0.3 or greater](http://maven.apache.org/) +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. You probably have 1.6 or 1.8. +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.7` +export JAVA_HOME=`/usr/libexec/java_home -v 1.8` export PATH=${JAVA_HOME}/bin:$PATH ``` @@ -80,7 +101,7 @@ export PATH=${JAVA_HOME}/bin:$PATH After cloning the project, you can build it from source with this command: ``` -mvn package +mvn clean package ``` ### Docker @@ -88,21 +109,27 @@ mvn package ``` git clone https://github.com/swagger-api/swagger-codegen - cd swagger-codegen - ./run-in-docker.sh mvn package ``` -#### Build a Node.js server stub + +#### Run Docker in Vagrant +Prerequisite: install [Vagrant](https://www.vagrantup.com/downloads.html) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads). ``` -./run-in-docker.sh generate \ - -i http://petstore.swagger.io/v2/swagger.json \ - -l nodejs \ - -o samples/server/petstore/nodejs +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 Docker image + +https://hub.docker.com/r/swaggerapi/swagger-generator/ + ### Homebrew To install, run `brew install swagger-codegen` @@ -110,7 +137,27 @@ Here is an example usage: ``` swagger-codegen generate -i http://petstore.swagger.io/v2/swagger.json -l ruby -o /tmp/test/ ``` +## 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 relesae) directly from [maven.org]( http://central.maven.org/maven2/io/swagger/swagger-codegen/2.2.0/swagger-codegen-2.2.0.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: @@ -119,7 +166,7 @@ You can build a client against the swagger sample [petstore](http://petstore.swa ./bin/java-petstore.sh ``` -(On Windows, run `./bin/windows/java-petstore.bat` instead) +(On Windows, run `.\bin\windows\java-petstore.bat` instead) This will run the generator with this command: @@ -134,18 +181,27 @@ with a number of options. You can get the options with the `help generate` comm ``` NAME - swagger generate - Generate code with chosen lang + swagger-codegen-cli generate - Generate code with chosen lang SYNOPSIS - swagger generate [(-a | --auth )] + swagger-codegen-cli generate + [(-a | --auth )] + [--additional-properties ] + [--api-package ] [--artifact-id ] + [--artifact-version ] [(-c | --config )] - [-D ] + [-D ] [--group-id ] (-i | --input-spec ) + [--import-mappings ] + [--instantiation-types ] + [--invoker-package ] (-l | --lang ) + [--language-specific-primitives ] + [--library ] [--model-package ] [(-o | --output )] - [(-t