diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000000..75ea5de6ca2 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,47 @@ +*.iml +out/ +*.ipr +*.iws +classpath.txt +version.properties +.project +.classpath +lib/* +build/* +generated-files/* +generated-sources/* +generated-code/* +*.swp +*.swo + +/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/default/hello.txt +samples/client/petstore/objc/Build +samples/client/petstore/objc/Pods +samples/server/petstore/nodejs/node_modules +target +.idea +.lib +atlassian-ide-plugin.xml +.DS_Store + +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/ diff --git a/.gitignore b/.gitignore index 91755b09d77..4b5649d69b5 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,67 @@ version.properties lib/* build/* generated-files/* +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/default/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 +atlassian-ide-plugin.xml +.DS_Store +packages/ +.pub +.packages +.vagrant/ + +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/perl/deep_module_test/ + +samples/client/petstore/python/.projectile +samples/client/petstore/python/.venv/ +samples/client/petstore/python/dev-requirements.txt.log + +.settings + +*.mustache~ +*.java~ +*.pm~ +*.xml~ +*.t~ + +samples/client/petstore/csharp/SwaggerClientTest/bin/Debug/ +samples/client/petstore/csharp/SwaggerClientTest/obj/Debug/ +**/.gradle/ diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 00000000000..46bb326da69 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,21 @@ +sudo: required +language: java +jdk: + - oraclejdk7 + - oraclejdk8 + +services: + - docker + +before_install: + # required when sudo: required for the Ruby petstore tests + - gem install bundler + +install: + +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 new file mode 100644 index 00000000000..7758d8166d1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,63 @@ +# Guidelines For Contributing + +## 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 OpenAPI Spec for reproducing the issue (:bulb: use [Gist](https://gist.github.com) to share). If the OpenAPI 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" + +## 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. + +## 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 langauages: +- C#: https://msdn.microsoft.com/en-us/library/vstudio/ff926074.aspx +- Java: https://google.github.io/styleguide/javaguide.html +- JavaScript - https://github.com/airbnb/javascript/tree/master/es5 +- ObjC: https://github.com/NYTimes/objective-c-style-guide +- 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 +- 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. + +### 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) +- 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) diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000000..0a3d093290e --- /dev/null +++ b/Dockerfile @@ -0,0 +1,13 @@ +FROM maven:3.3-jdk-7 + +WORKDIR /src +VOLUME /src +VOLUME /root/.m2/repository + +ADD . /opt/swagger-codegen + +RUN cd /opt/swagger-codegen && mvn package + +ENTRYPOINT ["java", "-jar", "/opt/swagger-codegen/modules/swagger-codegen-cli/target/swagger-codegen-cli.jar"] + +CMD ["help"] 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 2c4cfd3bac2..f6d73a877c3 100644 --- a/README.md +++ b/README.md @@ -1,177 +1,643 @@ -# Swagger Client Code-Generator +# Swagger Code Generator + +[![Build Status](https://travis-ci.org/swagger-api/swagger-codegen.svg)](https://travis-ci.org/swagger-api/swagger-codegen) +[![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 a project to build the Swagger code-gen library which can be used to automatically -generate client libraries from a Swagger-compliant server. It also contains a testing -framework which allows the client library to query an API server and validate expected results -You can find out more about both the spec and the framework at http://swagger.wordnik.com. For -more information about Wordnik's APIs, please visit http://developer.wordnik.com. +This is the swagger codegen project, which allows generation of client libraries automatically from a Swagger-compliant server. + +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 + + - [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) + - 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) + - [Node.js](#nodejs) + - [PHP Slim](#php-slim) + - [PHP Silex](#php-silex) + - [Python Flask (Connexion)](#python-flask-connexion) + - [Ruby Sinatra](#ruby-sinatra) + - [Scala Scalatra](#scala-scalatra) + - [Java JAX-RS (Java JAX-RS (Jersey v1.18)](#java-jax-rs-jersey-v118) + - [Java JAX-RS (Apache CXF 3)](#java-jax-rs-apache-cxf-3) + - [Java Spring MVC](#java-spring-mvc) + - [Haskell Servant](#haskell-servant) + - [To build the codegen library](#to-build-the-codegen-library) + - [Workflow Integration](#workflow-integration) + - [Online Generators](#online-generators) + - [Guidelines for Contribution](https://github.com/swagger-api/swagger-codegen/wiki/Guidelines-for-Contribution) + - [License](#license) + + +## Compatibility +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 | OpenAPI Spec compatibility | Notes +-------------------------- | ------------ | -------------------------- | ----- +2.1.6-SNAPSHOT | | 1.0, 1.1, 1.2, 2.0 | [master](https://github.com/swagger-api/swagger-codegen) +2.1.5 (**current stable**) | 2015-01-06 | 1.0, 1.1, 1.2, 2.0 | [tag v2.1.5](https://github.com/swagger-api/swagger-codegen/tree/v2.1.5) +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 1.6 or greater (http://java.oracle.com) +``` +wget http://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.1.4/swagger-codegen-cli-2.1.4.jar swagger-codegen-cli.jar -
  • - Apache ant 1.7 or greater (http://ant.apache.org/) +java -jar swagger-codegen-cli.jar help +``` -
  • - Scala 2.x or greater (http://www.scala-lang.org/downloads) +On a mac, it's even easier with `brew`: +``` +brew install swagger-codegen +``` -### To build the codegen library -If you don't have the Apache Ivy dependency manager installed, run this build script: +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.0.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 package +``` + +### Docker +#### Build and run using docker + +``` +git clone https://github.com/swagger-api/swagger-codegen +cd swagger-codegen +./run-in-docker.sh mvn package + ``` + + + +#### 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 Docker image + +https://hub.docker.com/r/swaggerapi/swagger-generator/ + +### 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/ +``` + + +### 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: + +``` +NAME + swagger generate - Generate code with chosen lang + +SYNOPSIS + swagger generate [(-a | --auth )] + [(-c | --config )] + [-D ] + (-i | --input-spec ) + (-l | --lang ) + [(-o | --output )] + [(-t