Week 11: Explosive Improvements Incoming!
Marvin
📅 August 11 – August 17
What I Planned to Do
Move the logic from my mini mojo to my comprehensive openapi maven plugin, and debug and resolve any errors that arise
To come up with the final steps of aggregating the openapi specs and displaying accurate documentation
What I Worked On
Last week I was making a mini mojo that implemented basic module detection and scanning, and the goal was to port the changes into the actual plugin
The complexity of the large plugin was that it had a maven plugin, JUnit test, Base test context, forked JVM and so many added dependencies on it
I started with a basic scanning inside the plugin, but I wasn’t able to properly input the properties inside the mojo like I wanted, so read through the dependencies and how they interacted with each other
Progress was very slow as I didn’t even know where to start and putting so much time in trying to find a way to even try anything seemed far fetched
I handled the property types which the original schema introspector couldn’t resolve in a file called
PropertyTypeResolverwhich I removed and added its useful methods inside the introspector for uniquenessThe main issue with making the plugin module averse was that spring context and JUnit dependencies were too coupled with the REST module, so I had to figure out how to manage that for other modules
Since we currently use
RestServices.getResourceHandlers()for the REST module using the test context I was skeptical whether this would work for any other moduleWhen I tried making the plugin work through the pom file of the concerned module, I was met with heavy classpath issues, with various dependencies not present and most importantly the JUnit test not coupling with the JAR file
I got to know that the src/test/ directory files are not included in the main-jar which resulted me in trying other methods like moving the test files to src/main/ and running the test in a JUnit runner
But I kept on running into a lot of spring context issues as the
BaseModulecontext is not configured to run this way and this is where I spent the next few days figuring things outI attended the week’s platform call and was recommended to take inspiration from the maven-surefire plugin as it did the module independent logic correctly as it worked anywhere
After a lot of trial and errors I couldn’t make it work for my plugin as it contained too many complex relationships that my maven plugin + JUnit architecture couldn’t handle
The classpath issues weren’t going anywhere so I abandoned the surefire plugin approached and looked for other ways to go about it
I decided I’ll dynamically make the classpath of the forked JVM using the module where it is hosted, this let me include dependencies that my plugin needed compulsorily
I tried to run this on the queues module, but it ran on platform version 2.3.4 and my JUnit dependencies required atleast 2.4.*+ versions as the versions before that had JUnit 4 instead of 5
I moved to test my changes on the REST module and after a lot of clever workarounds and so much trial and errors I was successful in generating the openAPI specs for omod-2.4 of the REST module
It worked for omod-2.5 and all other omod’s as well all through hosting this in the pom file and decoupled from the plugins pom file which was the biggest win I could ask for
It all came through making a
ModuleClasspathBuilderwhich included all necessary dependencies and using the test-jar plugin to convert the test files into the test-jar and including it in the classpath which was revolutionaryBut at this point I had hardcoded dependencies of swagger, jackson and JUnit and openmrs api and web which made it highly brittle and non-configureable
I did some changes to remove all the hardcoding and dynamically use the pom file dependencies to use it in the classpath to use it in other modules which was a success
After this win I moved back to the queues module and started testing to migrate it to REST version 2.4.6, and after careful attempts I solved all errors and ran the build successfully
I added the dependencies required for the plugin in the queues omod pom file then ran the plugin successfully which was another big achievement
One issue that plagued the plugin was that the openAPI spec generated module wise was 15000 lines for queues which also included resources from REST due to test context
I added filtering logic which only included resource handlers which had the necessary package names which made the spec accurate and decreased line number to 700
The problem that we saw was that there generated a lot of broken $ref links which was expected and would mostly be the final nail in this project, and figuring this out would be a good end then get to polishing
But it was easier said than done, but mostly the issue was naming convention inconsistencies, and this should be doable in the coming days
I also hammered out additional requirements of enabling the plugin to generate multiple specs for versions that we specify in the pom file config
I also removed the discriminator object from the spec generation since it was being used in the wrong way and the spec is more accurate without it
I also improved the $ref linking to nested objects as well as outlining what rep it links to
Finally, I replicated the
asRef()andasDefaultRep()methods in the test context as a fallback to the resource handlers which didn’t handle these reps in thegetRepresentationDescription()method
Challenges Faced
To handle major dependency issues, handle the plugin to not have the REST module hardcoded instead use the pom file application approach and use the dependencies there
Handle the classpath errors that occurred, because figuring out what component needs what files was a big challenge, but careful planning and logical inclusion helped me solve it
Handling spring context issues was definitely not easy but not giving up and keeping at it helped me generously
Commits/PRs This Week
PR Title: Initial implementation of OpenAPI Generator Maven Plugin with JavaParser integration
Status:
DraftCheck out my plugin repository: https://github.com/capernix/openmrs-maven-plugin-openapi
My Demo Video: https://youtu.be/SQ_ksJfMjsA?si=AiG1momcw8HO-HIC
Plans for Next Week
To handle the inconsistent naming convention issues and figure out a standard way of having a single source of truth for all naming purposes.
To clean up the code and prepare all the required documentation, usage guidelines and further improvements documents clearly outlined
To verify the swagger UI generation is on point and couple it with the maven plugin so the spec files can be readily viewed and taken advantage of
Notes/Discussion Points
The community as always were a big part of my awesome progress, and my mentors were more than helpful in guiding me and keeping me on track
I’m fully excited for my last week contributing for Google Summer of Code, and I’d like to end it on a high note on making something impactful and robust
Thank you!
Subscribe to my newsletter
Read articles from Marvin directly inside your inbox. Subscribe to the newsletter, and don't miss out.
Written by
Marvin
Marvin
21 | cs sophomore @ SPIT Mumbai | GSoC 2025 Contributor @ OpenMRS | Backend Dev | Java, Python, Spring Boot, Maven