Skip to content
GitLab

Server stub generator HOWTO · Changes

Page history
Initial Wiki authored by Jeremie Bresson's avatar Jeremie Bresson
Hide whitespace changes
Inline Side-by-side
Server-stub-generator-HOWTO.md 0 → 100644
View page @ 016d8b1b
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](#erlang)
- [Node.js](#nodejs)
- [PHP Lumen](#php-lumen)
- [PHP Slim](#php-slim)
- [PHP Silex](#php-silex)
- [Python Flask (Connexion)](#python-flask-connexion)
- [Python2 Flask (Connexion)](#python2-flask-connexion)
- [Ruby on Rails5](#ruby-on-rails-5)
- [Ruby Sinatra](#ruby-sinatra)
- [Scala Scalatra](#scala-scalatra)
- [Java JAX-RS 2.0 spec](#java-jax-rs-20-spec)
- [Java JAX-RS (Java JAX-RS (Jersey)](#java-jax-rs-jersey)
- [Java JAX-RS (Apache CXF 2 / 3)](#java-jax-rs-apache-cxf-2--3)
- [Java JAX-RS (Resteasy)](#java-jax-rs-resteasy)
- [Java JAX-RS (Apache CXF framework on Java EE server supporting CDI)](#java-jax-rs-apache-cxf-framework-on-java-ee-server-supporting-cdi)
- [Java Spring MVC](#java-spring-mvc)
- [Java SpringBoot](#java-springboot)
- [Java Undertow](#java-undertow)
- [Java MSF4J](#java-msf4j)
- [Haskell Servant](#haskell-servant)
- [ASP.NET Core 1.0](#aspnet-core-10)
- [Go Server](#go-server)
- [NancyFX](#nancyfx-module)
## [List of server frameworks supported by OpenAPI Generator](https://github.com/openapitools/openapi-generator/wiki/Server-stub-generator-HOWTO#list-of-server-frameworks-supported-by-swagger-codegen-1)
### Erlang
```
java -jar modules/openapi-generator-cli/target/openapi-generator-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/openapitools/openapi-generator
cd swagger-codegen
mvn clean package
java -jar modules/openapi-generator-cli/target/openapi-generator-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/openapitools/openapi-generator
cd swagger-codegen
mvn clean package
java -jar modules/openapi-generator-cli/target/openapi-generator-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/openapitools/openapi-generator
cd swagger-codegen
mvn clean package
java -jar modules/openapi-generator-cli/target/openapi-generator-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/openapitools/openapi-generator
cd swagger-codegen
mvn clean package
java -jar modules/openapi-generator-cli/target/openapi-generator-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/openapitools/openapi-generator
cd swagger-codegen
mvn clean package
java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
-i http://petstore.swagger.io/v2/swagger.json \
-l php-silex \
-o samples/server/petstore/silex
```
### Python Flask (Connexion)
```
java -jar modules/openapi-generator-cli/target/openapi-generator-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/openapi-generator-cli/target/openapi-generator-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/openapi-generator-cli/target/openapi-generator-cli.jar generate \
-i http://petstore.swagger.io/v2/swagger.json \
-l rails5 \
-o samples/server/petstore/rails5
```
### Ruby Sinatra
```
java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
-i http://petstore.swagger.io/v2/swagger.json \
-l sinatra \
-o samples/server/petstore/sinatra
```
### Scala Scalatra
```
java -jar modules/openapi-generator-cli/target/openapi-generator-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/openapi-generator-cli/target/openapi-generator-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/openapi-generator-cli/target/openapi-generator-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/openapi-generator-cli/target/openapi-generator-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/openapi-generator-cli/target/openapi-generator-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:
```xml
<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/openapi-generator-cli/target/openapi-generator-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/openapi-generator-cli/target/openapi-generator-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/openapi-generator-cli/target/openapi-generator-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/openapi-generator-cli/target/openapi-generator-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/openapi-generator-cli/target/openapi-generator-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/openapi-generator-cli/target/openapi-generator-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/openapi-generator-cli/target/openapi-generator-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/openapi-generator-cli/target/openapi-generator-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/openapi-generator-cli/target/openapi-generator-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/openapitools/openapi-generator
cd swagger-codegen
mvn clean package
java -jar modules/openapi-generator-cli/target/openapi-generator-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/openapitools/openapi-generator
cd swagger-codegen
mvn clean package
java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
-i http://petstore.swagger.io/v2/swagger.json \
-l nancyfx \
-o samples/server/petstore/nancyfx
```
## List of server frameworks supported by OpenAPI Generator
```
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
```
\ No newline at end of file