Week 12: The beginning of the end

📅 August 18 – August 24

---

What I Planned to Do

• 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

---

What I Worked On

• Last week was a big win in terms of what we were able to achieve with this maven plugin and this week went in documenting all this success, and pushing all this code in tangible PRs

• I started with the broken $refs as they needed immediate attention, they were the trickiest of the bunch as well as the naming logic in my plugin was very complex

• I started with trying to make sense of what names the API endpoints logic gave the $refs in oneOf object, and what the actual schema names were

• Usually, the difference occurred due to difference in pascalCase and kebab-case in oneOf and actual schemas respectively

• I started with creating a SchemaNameGenerator which was supposed to handle all naming logic and be the single source of truth for all my usecases

• I started with a few methods which converted kebab-case to PascalCase and returned it properly, but using these methods in oneOf declaration was proving to be difficult as I was guilty of a lot of tiers of naming inference logic

• Eventually I dug to the root of the problem, moved all that logic in the schema generator file as well and finally both the names were matching which was an absolute success

• In such a big file literally, all errors went away except for one: ConceptFull wasn’t being generated at all

• I knew the reason beforehand, and this was expected. ConceptResource is a peculiar resource handler in the sense that it doesn’t host its full representation logic inside getRepresentationDescription() method instead it has a @RepHandler named fullRepresentationDescription(), which took in a Concept delegate instead of a representation as a parameter

• But I hadn’t implemented the logic to scan it as I didn’t have a concept to use in the parameter, so I finally made a PoC logic where I hardcoded a concept creation and making both numeric and non-numeric concepts as the method had both properties

• I have kept it as a to-do to make it dynamic for any custom class and not only for conceptResource

• I also made a change in the schema where the ConceptFull schema has a oneOf pointing to two schemas which are numeric and non-numeric conceptFulls which made this schema even more impressive

• After all this I had my weekly meet with my mentor where I discussed all my successes, and I was suggested to document all the shortcomings of the plugin as that is the most essential work I have yet

• If I don’t do that properly then my plugin can’t be improved over time and there is a chance it could be not of use at all hence, I went ahead with making that my biggest priority

• With everything I was doing, I also pulled 3 pull requests with all of my progress with the plugin yet, my last 2-3 weeks progress and I asked my mentors to review it

• They reviewed it and I acted on them and improved the code and moved onto other tasks I had

• After this I was informed that my plugin has been successfully transferred under the OpenMRS banner! And it was also added to the local maven repository so I could add it to the REST and queues module without any errors

• This was the most satisfying part of the whole period, seeing my code actually be under the organization, on the verge of being adopted in the REST module

• I moved on to the next request which was to validate my generation against the live OpenMRS API endpoints and verify my plugin is working successfully

• I theorized that I could use a python script, hit the GET endpoints and directly compare the result with the spec but it wasn’t so straightforward

• I am now planning using REST assured with openapi4j or other spec parsing library and soon I’ll attach it with the PR and hopefully merge it with the REST and queues module

---

Challenges Faced

• Handling the naming logic was one of the most confusing periods as I didn’t know what went where and careful and patient parsing led to me successfully cracking it

• Creating a Concept object and managing it to be numeric or non-numeric turned out to be very complex as I had no resources but eventually it worked, but still keen on understanding it better

• Documenting the shortcomings of the plugin is very tough as something that we write thinking it is the best alternative usually escapes our keen eye so I’m hopeful the community will help in that regard

• Making a validation test is easier said than done and it’ll be an appropriate last job for the project

---

Commits/PRs This Week

1. PR Title: OPENAPI-01: Enhance the maven plugin to be module independent

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

• Status: Merged

1. PR Title: OPENAPI-02: Remove hardcoded dependencies from the plugin to make it modular

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

• Status: Merged

1. PR Title: OPENAPI-03: Fix the broken ref links and enhance the schema generation format

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

• Status: Opened

• Check out my plugin repository: openmrs/openmrs-contrib-openapi-maven-plugin

• My Demo Video: https://youtu.be/SQ_ksJfMjsA?si=AiG1momcw8HO-HIC

---

Plans for Next Week

• Last week!

---

Notes/Discussion Points

• I can’t believe this is my last blog, writing this blog every week on time, documenting every small thing was such a big part of my life that it doesn’t register that this is the last one I’ll write. I’m very grateful to everyone in the OpenMRS community for being the warmest and the most helpful bunch I had the pleasure of contributing alongside. I couldn’t have asked for a better place to contribute, especially my mentors who were helpful beyond belief and they were super helpful no matter what time it was. I want to thank you all for giving an opportunity to this guy and I promise I gave it my blood sweat and tears to make something meaningful which would help anyone who interacts with this community. I would write a longer paragraph in the final end blog, but I want to be grateful, and appreciative and I want to stay a part of this community hopefully for a long time. Thank you again.

---

Thank you!