Integration of Swagger into highly complex product tech stack, consisting of hundreds (300+) OSGi bundles, which included tenths of REST API endpoints, for automatic generation of Swagger spec from JAX RS services at runtime and viewing generated documentation via Swagger UI.

Some of the problems included:

  • Company’s product highly complex tech stack, consisting of hundreds (300+) OSGi bundles which included tenths of REST API endpoints, required generating Swagger spec from JAX RS services at runtime and viewing generated documentation via Swagger UI
  • Dependencies required by Swagger were incompatible with those used by Company’s product
  • None of the existing solutions for generating Swagger spec and HTML documentation from JAX RS services at build time – including ‘swagger-maven-plugin’ – worked due to non-Maven build of Company’s product
  • None of the existing solutions for generating Swagger spec from JAX RS services at runtime worked due to complex technology stack of Company’s product (OSGi container, Aries Blueprint, embedded Jetty, etc.) as well as bugs in its components – .e.g bug in Eclipse RAP platform used by Company’s product prevented using Apache CXF ‘swagger2feature’, dependency on CXF prevented using ‘OSGi - JAX RS Connector’ which used Jersey, etc.
  • Multiple issues with REST API endpoints’ metadata, including incorrect response codes, confusing operation names, lack of @Path annotations at class level, ignored custom response classes, etc.
  • Swagger UI was not accessible due to not being registered inside embedded Jetty server used by Company’s product

Some of the solutions applied included:

  • Researching and prototyping to understand how Swagger can be integrated into Company’s product
  • Implementing custom solution for both generating Swagger spec from JAX RS services at runtime and viewing generated documentation via Swagger UI, seamlessly integrated with complex technology stack used by Company’s product
  • Fixing issues with REST API endpoints’ metadata

Technology stack

  • Java
  • OSGi
  • Apache Aries Blueprint
  • Swagger 1.5

Industry

IT