swagger-sdk

ONAP uses micro-services architecture and each service is provided with REST API. Swagger could be used to represent the REST API definitions in JSON/YAML file and could be used to generate the server stub and client part in different language.

A new project called 'swagger sdk' is provided as part of ONAP MSB project and provides following features:

Build-Time support

1. Generate swagger.json during build-time and,
   1. Auto-generate the swagger.json under main/resources.
      NOTE:  Developer just need to annotate the REST API implementation with appropriate swagger annotations
   2. Install/deploy same swagger.json in to the maven repository [ Project Maven Group-id] ::[ Project maven artifact-id]-swagger-schema :: [project maven version]. 
2. Generate java client (sdk) during build-time and,
   1. Install/deploy java client in to the maven repository[ Project Maven Group-id] ::[ Project maven artifact-id]-java-sdk :: [project maven version]
3. Provides self-explanatory swagger.properties.sample where developer can configure the service specific swagger configuration like Service Root URI, swagger document license, etc.

 How to use?

1. Create swagger.properties by referring the given sample in this project and check-in it

How  to enable auto generation of Java SDK ?

Define -Dswaggersdk.generate-java-sdk=true  while build thru maven. By default this flag is absent.

How  to enable auto generation swagger.json ?

Define -Dswaggersdk.generate-json=true while build thru maven. By default this flag is absent.

Run-Time support

1. Generate swagger.json during run-time and expose the REST API at URI <Service Root URI>/swagger.json. 
   NOTE:  Developer just need to annotate the REST API implementation with appropriate swagger annotations
2. If the given project already has the swagger.json at the resources folder, it will expose it in the above mentioned URI instead of auto-generating.

   How to use?

1. Either annotate the service with required swagger annotations or place already defined swagger.json under main/resources folder.
2. Add following settings in the service spring.xml
   <import resource="classpath:META-INF/onap-swagger-sdk/swagger-config.xml" />

Advantages

1. Saves developer effort across different services by capturing all swagger related settings in one project
2. Brings uniformity across services to provide required swagger.json at pre-defined URI
3. Auto-generate the required client libraries (sdk) and make it available as part of the nexus. (currently it supports java and in future it could be enhanced to support more languages) 
4. Any external application like GUI, CLI or any internal services (say sdno-vpc) can directly integrate with other services (say msb) by adding dependency to the depending service's (msb) java sdk. This helps to identify any changes in dependent service's REST API during the build time itself, which saves the integrity of ONAP integration points across dependent services.

Documents

• Paris summit