DOCUMENTING MULTIPLE REST API VERSIONS USING SPRING BOOT, JERSEY AND SWAGGER
A few days ago I was completing the accompanying source code for Microservices using Spring Boot, Jersey, Swagger and Docker blog entry and found some problems while adding documentation support to multiple implementation versions of the “Hello” JAX-RS resource endpoints where the version information was passed in the URL or Accept Header.
Recapping the details, I stated my belief that Swagger’s BeanConfig singleton instantiation approach wasn’t going to work. The reason I believe so is because a BeanConfig instance dynamically creates only one Swagger definition file and it would require one definition file for each version. Yes, there are some “hacks” to get away with it, like removing the endpoints implementation where the version is passed in the Accept Header and then only one Swagger definition file will include the documentation for every endpoint implementation version. I don’t think this is the right answer though.
This post and its accompanying source code will tackle on this issue and demonstrate how to generate multiple Swagger definition files to feed Swagger UI to display JAX-RS APIs documentation for multiple implementation versions.
The accompanying source code has been refactored to match the packages as described in this post.
Add the entry point to the application via start-class property and Swagger dependency to pom.xml.
This is a snippet of the app’s entry point, that allows this application to be built and run as either a fat jar or as a war in a Servlet Container.
IMPLEMENT MULTIPLE VERSIONS OF THE JAX-RS ENDPOINTS USING JERSEY
At this point spring-boot-starter-jersey and spring-boot-starter-web are already dependencies of the application, this is important because they need to be mapped to different paths, Jersey’s will provide access to the Resources endpoints while Spring MVC will provide access to Actuator endpoints, for more detailed information, please visit Microservices using Spring Boot, Jersey, Swagger and Docker
JAX-RS providers, endpoints, etc.. are registered in a subclass of Jersey’s ResourceConfig class.
It could be noticed there is not reference to Swagger’s BeanConfig as it was in
previous blog post.
Next comes the HelloWorldV1 (Version 1) resource implementation which include both JAX-RS and Swagger annotations:
Next download Swagger UI zip file from https://github.com/swagger-api/swagger-ui/releases, 2.1.4 was used for the example app bundled with this post.
Extract and move resulting content to src/main/resources/static.
Create directories v1 and v2 in src/main/resources/static and place a copy of previously extracted index.html in them, then remove the one found in static folder.
Update index.html located in both, static/v1 and static/v2 directories for Swagger UI to find Swagger definition files.
in …/static/v1/index.html and:
Since there aren’t any Swagger defintion file yet, the application would run but there wouldn’t be any documentation available, let’s generate them:
swagger-maven-plugin is bounded to Maven compile phase, which will generate json definition files in target/classes/static/v1 and target/classes/static/v2 as configured in pom.xml and will be included in the resulting jar application along with their corresponding index.html.
RUNNING THE APPLICATION
Accessing the endpoints:
Create resource - Version 1 in Accept Header
Create resource - Version 2 in Accept Header
Some screenshots taken from running the application:
Hello Resource - Version 1
Hello Resource - Version 2
And that’s all for now.
Accompanying source code for this blog post can be found at: