/swagger-codegen

Server stub generator HOWTO

johnglacken edited this page Mar 8, 2017 · 38 revisions

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.

List of server frameworks supported by Swagger Codegen

Erlang

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l erlang-server \
  -o samples/server/petstore/erlang

Node.js

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 nodejs-server \
  -o samples/server/petstore/nodejs

To enable Google Cloud Function

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

PHP 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 http://petstore.swagger.io/v2/swagger.json \
  -l lumen \
  -o samples/server/petstore/lumen

PHP 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 http://petstore.swagger.io/v2/swagger.json \
  -l slim \
  -o samples/server/petstore/slim

PHP 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 http://petstore.swagger.io/v2/swagger.json \
  -l silex-PHP \
  -o samples/server/petstore/silex

Python Flask (Connexion)

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l python-flask \
  -o samples/server/petstore/flaskConnexion

Python2 Flask (Connexion)

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l python-flask \
  -o samples/server/petstore/flaskConnexion-python2 \
  -D supportPython2=true

Ruby On Rails 5

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l rails5 \
  -o samples/server/petstore/rails5

Ruby Sinatra

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l sinatra \
  -o samples/server/petstore/sinatra

Scala Scalatra

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l scalatra \
  -o samples/server/petstore/scalatra

Java JAX-RS (2.0 Spec)

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l jaxrs-spec \
  -o samples/server/petstore/jaxrs-spec

Java JAX-RS (Jersey)

The default use Jersey 2.x

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l jaxrs \
  -o samples/server/petstore/jaxrs/jersey2

To use Jersey 1.x:

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l jaxrs --library=jersey1 \
  -o samples/server/petstore/jaxrs/jersey1

Java JAX-RS (Apache CXF 2 / 3)

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://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)

Features since release 2.2.2:

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)

CXF 2

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

Java JAX-RS (Resteasy)

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l jaxrs-resteasy \
  -o samples/server/petstore/jaxrs-resteasy/default

Java JAX-RS (Resteasy) for Jboss EAP

Since 2.2.2

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l jaxrs-resteasy-eap \
  -o samples/server/petstore/jaxrs-resteasy/eap

Features:

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)

Java JAX-RS (Apache CXF framework on Java EE server supporting CDI)

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l jaxrs-cxf-cdi \
  -o samples/server/petstore/jaxrs-cxf-cdi

Java Spring MVC

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l spring --library spring-mvc\
  -o samples/server/petstore/spring-mvc

Java SpringBoot

spring generator uses SpringBoot as the default library

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://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

Java Undertow

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l undertow \
  -o samples/server/petstore/undertow

Java MSF4J

Java Micro Services Framework For Java

MSF4J generator uses java-msf4j as the default library

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://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

Haskell Servant

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  -l haskell-servant \
  -o samples/server/petstore/haskell-servant

ASP.NET Core 1.0

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
  -i http://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

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 http://petstore.swagger.io/v2/swagger.json \
  -l go-server \
  -o samples/server/petstore/go-server

NancyFX Module

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 nancyfx \
  -o samples/server/petstore/nancyfx

List of server frameworks supported by Swagger Codegen

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