GSoC 2025 : Enhancing OpenAPI Documentation Generation - Final Evaluation

• Project Title: Enhancing OpenAPI Documentation Generation

• Primary mentor: Chi Bong Ho

• Backup mentor: Herman Muhereza

• Student: Marvin Sukumar

• Project Link: Enhancing OpenAPI Documentation Generation - Projects

Overview

The API Documentation being produced were inconsistent with the actual response which resulted in difficulties to work with APIs. A solution was required to bring the documentation generation phase from run-time to build-time and move away from the broken methods to more accurate approaches.

The goal of my project was to build a custom Maven plugin that analyzes the REST resources directly at build-time ensuring that the generated OpenAPI spec always reflects the true contract of the APIs.

Objectives

The primary objectives of this project were:

• Develop a Maven plugin that generates OpenAPI 3.0-compliant specifications through direct code analysis, eliminating documentation drift

• Engineer a minimal-configuration solution that works seamlessly across all OpenMRS modules without requiring manual schema definitions

• Deliver comprehensive documentation, examples, and usage patterns that make the plugin immediately accessible to OpenMRS developers

Repository

Main OpenMRS repository:

https://github.com/openmrs/openmrs-contrib-openapi-maven-plugin

Repository which has a minimal implementation of a maven plugin to understand module classpath management

https://github.com/capernix/openmrs-module-averse-openapi-plugin

Pull Requests

RESTWS-975: Implement Resource Schema Introspection Endpoint by capernix · Pull Request #649 · openmrs/openmrs-module-webservices.rest

RESTWS-980: Initial implementation of OpenAPI Generator Maven Plugin with JavaParser integration by capernix · Pull Request #657 · openmrs/openmrs-module-webservices.rest

OPENAPI-01: Enhance the maven plugin to be module independent by capernix · Pull Request #2 · capernix/openmrs-maven-plugin-openapi

OPENAPI-02: Remove hardcoded dependencies from the plugin to make it modular by capernix · Pull Request #3 · capernix/openmrs-maven-plugin-openapi

OPENAPI-03: Fix the broken ref links and enhance the schema generation format by capernix · Pull Request #1 · openmrs/openmrs-contrib-openapi-maven-plugin

openmrs/openmrs-contrib-openapi-maven-plugin

Weekly Blog Posts

Talk Threads

GSoC 2025: Enhancing OpenAPI Documentation Generation - Weekly Updates & Talk - Community / GSoC - OpenMRS Talk

Proposal

https://drive.google.com/file/d/1ckS1XvLZ4KjQ1KWZneprzeAgBrbnPcUh/view?usp=sharing

Task Achieved

Over the course of this project, the things I managed to do were

• Created a maven plugin that runs at build-time by applying it in any module and receiving accurate OpenAPI-3.0 compliant specification

• Successfully leveraged the OpenMRS test context to access critical methods and integrated it with the maven plugin which runs inside an isolated JVM with its own classpath

• Created a one-of-its-kind schema introspector which comprehensively scans through the module using reflection and collects all properties of a particular resource handler through multiple avenues like Delegate classes, superclasses and @PropertyGetter methods.

• Removes the dependency from the legacy getGETModel() methods and directly accesses the property methods completely eliminating redundant and deprecated methods

• Upgrades the schema version from Swagger 2.0 to OpenAPI-3.0, leveraging the use of oneOf object to accurately document the representation-dependent endpoints the right way

• The automatically generated OpenAPI specification from the REST module is validated to be atleast 92.5% accurate down to the types with the actual API response tested against 46 live endpoints with all representations included.

Future Works

This project paves a massive foundation for championing accurate OpenAPI documentation with brand new schema instrospection logic and first-of-its-kind ability to get comprehensive list of properties you can access with custom representation. That being said, there’s a lot of room to improve and implement additional features, and without documenting the shortcomings accurately the project ceases to grow and improve properly.

• Currently the OpenAPI spec being produced covers only the GET endpoints. Additional coverage of POST, DELETE, and UPDATE is required to make the spec truly comprehensive

• The schema handles only the main resource files (i.e. the ones with @Resource annotation), and Sub-resources are instead documented by mentioning it in description like:

        "answers" : {
            "type" : "array",
            "items" : {
              "type" : "string",
              "description" : "Sub-resource: FieldAnswer",
              "example" : "FieldAnswer data as string"
            }
          }

The goal should be to treat them the same as resources and generate their schemas as well for better documentation

• The main test class that handles the generation logic (i.e. the OpenmrsOpenapiSpecGeneratorTest.java) handles type inference in a tier-based logic and it fallbacks to string if nothing is satisfied, ideally it should not need any fallbacks so any concrete inference approaches would help

• Handling of collections like Set, List and Maps are hardcoded in the test file, along with domain names and overall, the property type naming logic of the test class would be better with a more concrete approach

• Better support of @RepHandler would enable us to scan representations other than the standard ones and move away from hardcoding those representations at places

• Collection vs item detection in the OpenAPI spec needs improvement

• Currently if a property returns null then the validation fails since it is not built to recognize it can be nullable. Adding the nullable logic would be a welcome addition

• Schema introspector has a good foundation but it could need some improvements to catch a wider range of properties that it could be missing, although this is not critical

• The ConceptFull class has both numeric and non-numeric class which is different than the property method, so a concept object is created for it. Ideally it should be created for any resource handler that requires it

• Support for Javadocs integration would be a welcome addition

Mid-term Evaluation

GSoC 2025 | Enhancing OpenAPI Documentation Generation Mid-terms

Final Evaluation

GSoC 2025 | Enhancing OpenAPI Documentation Generation | Final Evaluation

Experience with GSoC

When I started this journey of open-source I was already fascinated with the idea of contributing to something bigger than me, and I never could’ve imagined it would start with one of the most rewarding programs like this. And it was worth the hype, as it introduced me to elevating from a guy new to this side of the wall, to actually creating and contributing to actual meaningful projects with people who are so passionate for the cause. These 3 months I tried new technologies, worked my way through massive messy codebases and saw myself creating things I couldn’t imagine before. And I’ll be grateful for it.

I’d like to thank everyone at OpenMRS for being welcoming and helping me grow at such a rapid pace. I’ll forever be thankful to my mentor Chi Bong Ho who guided me right from project selection, encouraged me all the way through and helped me every step of the way by helping me through countless issues, it really made this program go so smooth and honestly couldn’t have asked for a better guide. I’d also thank Herman Muhereza for being my go-to guide for technical doubts and for his constant help, even creating snippets and architecture designs which I really appreciate. Jayasanka and Beryl for being the best org admins, and all the community members, specially Rafal whose ideas completely shaped this project for the better and thank you to Daniel and Ian as well for the constant guidance. I hope I can further contribute to this community and improve it for everyone.

Thank you for the best 3 months of my life, I’ll end my program in the highest of spirits!