Skip to content

Server stub generator HOWTO

Jump to bottom
wing328 edited this page Sep 19, 2016 · 44 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.

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

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

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

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)

Update (scheduled for 2.1.5):

This Codegen will generate a complete web application stub.

  • supports bean-validation-api annotations (currently not supported by CXF wadl2java...)
  • uses the CXF 3 Swagger2Feature for supplying the Swagger-API
  • provides 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
  • configuration files 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

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

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 5 Web API

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

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

would suggest when compiling to use flag to ignore tests. The tests requires extra dependencies and the compilation might fail due to that.

Navigation

Codegen Usage

Clone this wiki locally