Week 4: Strategizing the right moves!

📅 June 21–27

What I Planned to Do

• Handle the edge cases, particularly the ConceptResource1_8 where there exist multiple representations like fullchildren

• Perfect the schema format better and consult and understand how to export it in a YAML or JSON format

---

What I Worked On

• This week I focused on creating a checkpoint on all the progress I have had till now, and put efforts to better my PR in the pursuit of merging it

• After a brief discussion with my mentors, we decided on a lot of things I detail below

• Firstly, lots of resource classes have representations which were handled by @RepHandlers which are methods used to specially handle any of the representations, whether it is ‘Default’ or ‘full’ or any of the resource-specific representations like ‘fullchildren’ in case of ConceptResource

• I was trying to handle that edge case but after pondering and talking about it, we came to the conclusion to gracefully ignore any resource classes implementing it for now and the solution should be created in the coming PRs

• We have to think about changing how things work at the REST module level so that we can type those functions better (without causing backwards compatibility). This likely means we'll have to rewrite some of the REST module functions

• I was also asked to remove the schema introspector code that I had committed in the PR since we didn’t intend to expose its endpoint to the public, rather use it for internal logic in the plugin

• After taking care of it in the code I removed the files and rebased it on top of the PR branch so I could later use it if needed

• I now came to the final task for this PR: Making this plugin run for all REST resource classes in the module in which this is implemented in instead of hardcoding each resource

• For this, first I got to clearing how we are going to implement this plugin in the REST module, and I had two approaches, adding this in the parent pom.xml file and it is scanning all omod directories, or having a per-module approach and adding this in each module pom file

• The config structure we have currently planned is as follows

<plugin>
    <groupId>org.openmrs.module</groupId>
    <artifactId>openapi-maven-plugin</artifactId>
    <version>${project.version}</version>
    <executions>
        <execution>
            <id>generate-spec</id>
            <phase>compile</phase>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <scanPackages>
                    <package>org.openmrs.module.webservices.rest.web.v1_0.resource</package>
                </scanPackages>
            </configuration>
        </execution>
        <execution>
            <id>aggregate-specs</id>
            <phase>package</phase>
            <goals>
                <goal>aggregate-specs</goal>
            </goals>
        </execution>
    </executions>
</plugin>

• This is a very clear plugin configuration where we use the scanPackages configuration parameter which is the discovery engine of the plugin

• While it doesn't currently perform explicit annotation scanning, it successfully identifies all REST resources in practice

• So, after talking about it, I got to know owing to the modular architecture of OpenMRS, we should implement a per-module approach

• But the question arises of duplication, in many of the cases, there are multiple files of the same resource in different omod directories, so which one do we choose?

• So, I put a discussion comment on my project thread in order to get the community feedback and decide on how to approach this situation

---

Challenges Faced

• Handling @RepHandler methods proved to be very tough on it’s own and needs a decent amount of time to get right

• Deciding on a per-module and module-wide approach was tricky and I definitely need the response of the project and community experts in this endeavor

• Even now, some of the resource classes fail to make an instance owing to them being a sub-resource and their main resource either being outside the omod directory or they need context, both of which need a case-by-case solution

---

What I Learned

• Learnt in-depth about the modular architecture of OpenMRS and how it affects each decision for the plugin

• Understood the concept of rebasing in more detail and successfully applied it

---

Commits/PRs This Week

• PR Title: Initial implementation of OpenAPI Generator Maven Plugin with JavaParser integration

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

• Status: Draft

---

Plans for Next Week

• Merge the PR and start working on handling @RepHandler methods or search handlers

• Discuss and decide on what resource class versions are to be taken to generate the OpenAPI specifications for

• Implement the plugin module wide and debug any edge cases that do arise

---

Notes/Discussion Points

• Try different methods from scratch, and apply those learnings when it does / doesn’t work

• Keep my mentor and the community more up to date with the success, the issues and everything about the project

---

Thank you!