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" />


  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.


  • No labels


  1. Hi Kanagaraj,

    Is it possible to leverage swagger sdk to generate the swagger.json during run time if the microservice is not using spring?



    1. user-67d6f

      Hi Huabing, No it does depends on the spring . for the best approach, its better to generate the swagger.json during build time and keep it as nexus maven artifact and it could be referred during the run time.

      1. Got it, thank you

  2. Hi Kanagaraj,

    If I don't have a spring in my environment, whether it possible to generate swagger.json during run-time?


    1. user-67d6f

      HI LiZi,

      It does support only for spring environment. in other case , you could still use sdk libarary to use it in your project as the java api instead of spring bean.

      Kanagaraj M

  3. Hi Kanagaraj,

    Is there any alternative to swagger for python code?

    Thanks and Regards


    1. user-67d6f

      Hi Aditya, currently swagger sdk is not enabled in python. currently it supports only for java.

      1. Thanks Kanagaraj.

        There is a module called drf_yasg for python components which more or less achieves the same.