Swagger Jersey generated server

1. Overview

This server was generated by the swagger-codegen project. By using the OpenAPI-Spec from a remote server, you can easily generate a server stub. This is an example of building a swagger-enabled JAX-RS server.

This example uses the JAX-RS framework.

To run the server, please execute the following:

mvn clean package jetty:run

You can then view the swagger listing here:

http://localhost:1234/swagger.json

Note that if you have configured the host to be something other than localhost, the calls through swagger-ui will be directed to that host and not localhost!

2. Debug

For other extension based on this project, the command mvnDebug clean package jetty:run is used to run it in debugging mode. The default debugging port is 8000.

3. RestClient Test

Firstly, you need a restClient tool. If you use Chrome browser, you can use its applications to simulate a restful client, for example, YARC (Yet Another REST Client).

3.1 service creation test

The HTTP request of service creation test contains

• URL: http://localhost:1234/restconf/data/tapi-common:context/tapi-connectivity:connectivity-context/
• Method: POST
• Headers:
  • Accept: application/json
  • Content-Type: application/json
• Payload:

{"tapi-connectivity:connectivity-service":[{"uuid":"f6447f09-64b9-46b7-b386-47dc71a2876d","service-layer":"PHOTONIC_MEDIA",
"service-type":"POINT_TO_POINT_CONNECTIVITY","end-point":[{"local-id":"22112233-5535-6677-8899-100000035182",
"layer-protocol-name":"PHOTONIC_MEDIA","layer-protocol-qualifier":"tapi-photonic-media:PHOTONIC_LAYER_QUALIFIER_NMC",
"service-interface-point":{"service-interface-point-uuid":"22112233-5535-6677-8899-100000035182"}},
{"local-id":"22112233-5535-6677-8899-100000035178","layer-protocol-name":"PHOTONIC_MEDIA",
"layer-protocol-qualifier":"tapi-photonic-media:PHOTONIC_LAYER_QUALIFIER_NMC","service-interface-point":
{"service-interface-point-uuid":"22112233-5535-6677-8899-100000035178"}}]}]}

The response is:201 - Created

4. Service-related interface

Service operation	URL	HTTP Request
Service Creation	http://localhost:1234/restconf/data/tapi-common:context/tapi-connectivity:connectivity-context/	POST
Service Deletion	http://localhost:1234/restconf/data/tapi-common:context/tapi-connectivity:connectivity-context/	DELETE
Service Query	http://localhost:1234/restconf/data/tapi-common:context/tapi-connectivity:connectivity-context/	GET

Notifications

The codes is generated automatically as listed:

Thanks to my colleague Diego we have been able to generate a Java Server Stub to be use for testing ODTN Phase 1.5 prototypes. As you might know the generated code is “empty” in the sense that it does not returns any TAPI objects when the different API entries are exercise by a REST Client app, currently the expected answer from any TAPI request is:
 
{"code":4,"type":"ok","message":"magic!"}
 
Following I explain the whole process employed to generate this server as I think it would be interesting to be included in a README file if we want to upload it to the official repositories.
 
Starting from the official ONF TAPI 2.1 yang models we have generated the conversion to swagger using the following command:
 
sudo java -jar ~/.m2/repository/com/mrv/yangtools/swagger-generator-cli/1.1.11-SNAPSHOT/swagger-generator-cli-1.1.11-SNAPSHOT-executable.jar -yang-dir YANG/ -format json -content-type application/json -output tapi-2.1.json tapi-topology tapi-common tapi-connectivity tapi-dsr tapi-eth tapi-notification tapi-oam tapi-path-computation tapi-photonic-media tapi-virtual-network
 
Subsequently I generated the server stub using the swagger-codegen-2.3.1 software downloaded from:
 
wget http://central.maven.org/maven2/io/swagger/swagger-codegen-cli/2.3.1/swagger-codegen-cli-2.3.1.jar -O swagger-codegen-cli.jar
 
Then we generated the server stub on Java JAX-RS (Jersey) using the following command:
 
java -jar swagger-codegen-cli-2.3.1.jar generate -i tapi-2.1.json -l jaxrs -o tapi2.1-javaServer
 
However it seems this latest versión of swagger-codegen has a bug (https://groups.google.com/forum/#!topic/swagger-swaggersocket/qceUgy2kpGQ) which we solved by removing the following line from the pom.xml included in the root folder of the generated server stub.
 
    <dependency>
    	<groupId>javax.validation</groupId>
    	<artifactId>validation-api</artifactId>
    	<version>1.1.0.Final</version>
        <scope>provided</scope>
    </dependency>
 
After this little modification the server stub is ready to be launched by:
 
mvn clean package jetty:run


Make sure of these conditions
I setup a new VM Ubuntu 16.04 LTS, I simply installed the openjdk-8-jdk, then the latest maven package:
 
/tapi2.1-javaServer$ mvn -v
Apache Maven 3.3.9
Maven home: /usr/share/maven
Java version: 1.8.0_181, vendor: Oracle Corporation
Java home: /usr/lib/jvm/java-8-openjdk-amd64/jre
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "4.13.0-36-generic", arch: "amd64", family: "unix"
 
And then I simply unzip the java server stub file “tapi2.1.zip” and I could get the server properly running by compiling and executing the server with:
 
mvn clean package jetty:run

1. Some Restful Response are filled in class DataApiServiceImpl;

2. In order to match the namespace prefix definition, some URIs defined in class DataApi are replaced:

Auto-generated	replaced
context	tapi-common:context
media-channel-service-interface-point-spec	tapi-photonic-media:media-channel-service-interface-point-spec
connectivity-service	tapi-connectivity:connectivity-service

3. The response json should also contains the namespace prefix as 2. mentioned. For device/port discovery, all Java annotations @JsonProperty("media-channel-service-interface-point-spec") are replaced by @JsonProperty("tapi-photonic-media:media-channel-service-interface-point-spec")