- Notifications
You must be signed in to change notification settings - Fork 6k
Server stub generator HOWTO
Here is the documentation to generate a server stub for a couple different frameworks. If you want to contribute to make it better, please click on the "Edit" button to update the documentation.
- ASP.NET Core 1.0
- Erlang
- Go Server
- Haskell Servant
- Java JAX-RS (Apache CXF 2 / 3)
- Java JAX-RS (Apache CXF framework on Java EE server supporting CDI)
- Java JAX-RS (Java JAX-RS (Jersey)
- Java JAX-RS (Resteasy)
- Java JAX-RS 2.0 spec
- Java MSF4J
- Java Spring MVC
- Java SpringBoot
- Java Undertow
- NancyFX
- Node.js
- PHP Lumen
- PHP Silex
- PHP Slim
- Python Flask (Connexion)
- Python2 Flask (Connexion)
- Ruby on Rails 5
- Ruby Sinatra
- Scala Scalatra
List of server frameworks supported by Swagger Codegen
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 https://petstore.swagger.io/v2/swagger.json \ -l erlang-server \ -o samples/server/petstore/erlang 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 https://petstore.swagger.io/v2/swagger.json \ -l nodejs-server \ -o samples/server/petstore/nodejs 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 https://petstore.swagger.io/v2/swagger.json \ -l nodejs-server --additional-properties=googleCloudFunctions=true \ -o samples/server/petstore/nodejs-google-cloud-function https://cloud.google.com/functions/docs/quickstart is a good starting point on how to deploy the generated code.
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 https://petstore.swagger.io/v2/swagger.json \ -l lumen \ -o samples/server/petstore/lumen 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 https://petstore.swagger.io/v2/swagger.json \ -l slim \ -o samples/server/petstore/slim 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 https://petstore.swagger.io/v2/swagger.json \ -l php-silex \ -o samples/server/petstore/silex 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 https://petstore.swagger.io/v2/swagger.json \ -l python-flask \ -o samples/server/petstore/flaskConnexion 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 https://petstore.swagger.io/v2/swagger.json \ -l python-flask \ -o samples/server/petstore/flaskConnexion-python2 \ -D supportPython2=true 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 https://petstore.swagger.io/v2/swagger.json \ -l rails5 \ -o samples/server/petstore/rails5 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 https://petstore.swagger.io/v2/swagger.json \ -l sinatra \ -o samples/server/petstore/sinatra 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 https://petstore.swagger.io/v2/swagger.json \ -l scalatra \ -o samples/server/petstore/scalatra 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 https://petstore.swagger.io/v2/swagger.json \ -l jaxrs-spec \ -o samples/server/petstore/jaxrs-spec The default use Jersey 2.x
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 https://petstore.swagger.io/v2/swagger.json \ -l jaxrs \ -o samples/server/petstore/jaxrs/jersey2 To use Jersey 1.x:
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 https://petstore.swagger.io/v2/swagger.json \ -l jaxrs --library=jersey1 \ -o samples/server/petstore/jaxrs/jersey1 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 https://petstore.swagger.io/v2/swagger.json \ -l jaxrs-cxf \ -o samples/server/petstore/jaxrs-cxf This Codegen only generate a minimalist server stub. You must add the CXF dependency to your classpath (eg: with Maven)
This Codegen will generate a complete web application stub.
The following features are supported using CLI-options:
- add beanvalidation annotations / use automatic serverside beanvalidation
- use the CXF3 Swagger2Feature for supplying a generated Swagger contract
- include Swagger-UI as a web-jar
- use the CXF WADLGenerator for supplying a generated WADL contract
- provide test classes for each operation (using JAXRSClientFactory)
- configuration dependencies:
- Jackson is used as provider (is already included as dependency of swagger-jaxrs)
- Spring is used for configuration of CXF
- use Spring-Boot for startup and for integration testing
- configuration file for Jboss is included (jboss-web.xml)
If you are using CXF v2.x, you must provided a custom ResourceComparator class. This class will help CXF to choose the good resource interface for mapping an incomming request. The default behavior of CXF v2.x is not correct when many resources interface have the same global path. See: See http://cxf.apache.org/docs/jax-rs-basics.html#JAX-RSBasics-Customselectionbetweenmultipleresources
You can found this class here: https://github.com/hiveship/CXF2-resource-comparator/blob/master/src/main/java/CXFInterfaceComparator.java TODO: This class could be directly generated by the Codegen.
You must register this class into your JAX-RS configuration file:
<jaxrs:resourceComparator> <bean class="your.package.CXFInterfaceComparator"/> </jaxrs:resourceComparator>This is no longer necessary if you are using CXF >=v3.x
git clone https://github.com/swagger-api/swagger-codegen cd swagger-codegen java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \ -i https://petstore.swagger.io/v2/swagger.json \ -l jaxrs-resteasy \ -o samples/server/petstore/jaxrs-resteasy/default Since 2.2.2
git clone https://github.com/swagger-api/swagger-codegen cd swagger-codegen java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \ -i https://petstore.swagger.io/v2/swagger.json \ -l jaxrs-resteasy-eap \ -o samples/server/petstore/jaxrs-resteasy/eap The following features are supported using CLI-options:
- This language will generate separate impl/interfaces.
- add beanvalidation annotations / use automatic serverside beanvalidation
- use the Resteasy SwaggerFeature for supplying a generated Swagger contract
- configuration file for Jboss is included (jboss-web.xml)
git clone https://github.com/swagger-api/swagger-codegen cd swagger-codegen java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \ -i https://petstore.swagger.io/v2/swagger.json \ -l jaxrs-cxf-cdi \ -o samples/server/petstore/jaxrs-cxf-cdi git clone https://github.com/swagger-api/swagger-codegen cd swagger-codegen java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \ -i https://petstore.swagger.io/v2/swagger.json \ -l spring --library spring-mvc\ -o samples/server/petstore/spring-mvc spring generator uses SpringBoot as the default library
git clone https://github.com/swagger-api/swagger-codegen cd swagger-codegen java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \ -i https://petstore.swagger.io/v2/swagger.json \ -l spring \ -o samples/server/petstore/springboot You can also set a Json file with basePackage & configPackage properties : Example :
{ "basePackage":"io.swagger", "configPackage":"io.swagger.config" } For use it add option -c myOptions.json to the generation command
To Use-it : in the generated folder try mvn package for build jar. Start your server java -jar target/swagger-springboot-server-1.0.0.jar SpringBoot listening on default port 8080
git clone https://github.com/swagger-api/swagger-codegen cd swagger-codegen java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \ -i https://petstore.swagger.io/v2/swagger.json \ -l undertow \ -o samples/server/petstore/undertow Java Micro Services Framework For Java
MSF4J generator uses java-msf4j as the default library
git clone https://github.com/swagger-api/swagger-codegen cd swagger-codegen java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \ -i https://petstore.swagger.io/v2/swagger.json \ -l msf4j \ -o samples/server/petstore/msf4j Before you build/run service replace .deploy(new PetApi()) with your actual service class name in Application.java file like .deploy(new ApisAPI()) then it will start that service. If you have multiple service classes add them in , separated manner.
new MicroservicesRunner() .deploy(new PetApi()) .start(); To Use-it : in the generated folder try mvn package for build jar, then start your server: java -jar target/micro-service-server-1.0.0.jar (Java Microservice listening on default port 8080)
Run the following command or simply go to http://127.0.0.1:8080/pet/12 from your browser:
curl http://127.0.0.1:8080/pet/12 git clone https://github.com/swagger-api/swagger-codegen cd swagger-codegen java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \ -i https://petstore.swagger.io/v2/swagger.json \ -l haskell-servant \ -o samples/server/petstore/haskell-servant git clone https://github.com/swagger-api/swagger-codegen cd swagger-codegen java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \ -i https://petstore.swagger.io/v2/swagger.json \ -l aspnetcore \ -o samples/server/petstore/aspnet5 aspnet5 has been deprecated. Please use aspnetcore instead.
If you're using Windows 10, please run the following to avoid any potential issue with file encoding:
set JAVA_OPTS=-Dfile.encoding=UTF-8 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 https://petstore.swagger.io/v2/swagger.json \ -l go-server \ -o samples/server/petstore/go-server 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 https://petstore.swagger.io/v2/swagger.json \ -l nancyfx \ -o samples/server/petstore/nancyfx aspnet5 (deprecated and replaced by aspnetcore) aspnetcore python-flask jaxrs jaxrs-cxf jaxrs-resteasy jaxrs-spec jaxrs-cxf-cdi inflector nancyfx nodejs-server scalatra silex-PHP sinatra rails5 slim spring haskell lumen go-server erlang-server undertow msf4j would suggest when compiling to use flag to ignore tests. The tests requires extra dependencies and the compilation might fail due to that.