-
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.