Week 8: The riddle of 'custom'!

📅 July 21 – July 27

---

What I Planned to Do

• To finalize on using the JSON output approach or direct OpenAPI spec generation method

• To create a proof-of-concept to showcase the ability and feasibility of either approach

• To start sculpting the skeleton of the schema, and improve any rough edges that arises

---

What I Worked On

• Last week, I was at a crossroads deciding whether to generate OpenAPI specs through a JSON output or skip the JSON file and directly generate the spec

• After conversing with my mentors, I decided to experiment more and kept the JSON output for the time being

• Currently, the JSON was very rough even though I was polishing it for GET endpoints, so my priority was generating the closest to ideal OpenAPI spec as I can

• As we have passed the midterm it was time to think about the end product so I started to refresh my knowledge on OpenAPI specs, what an ideal spec should look like, it’s samples and properties tied to the new OpenAPI 3.0

• I learnt that OpenAPI 3.0 has introduced a lot of Quality-of-life features which really helps document the REST API most accurately

• For API documentation, the most important factor is the REST APIs being both human readable and machine readable and producing the least amount of confusion in both

• The concept of representation was very poorly documented in our previous swagger 2.0 spec, in which rep(v) was defined once but it wasn’t clear to a new developer that changing value of v changes the structure of the response significantly

• This is not ideal, and OpenAPI 3.0 solves this problem by introducing a parameter known as oneOf, wherein all the schemas defined under oneOf tells the user that the response could and should match only one of the given schemas

• There also is a property called discriminator where we map what values of v would result in what type of schema

• This addition made the documentation so much more readable and understandable to the layman

• I started writing down some possible structures, and if you want to read more, I will release a blog solely on this concept for deeper analysis

• After continuous discussion and thinking I decided on my approach of oneOf and discriminator as it was clearly the most ideal for our use case

• Before I moved on with the changes, I had a 1:1 with my mentor where we discussed my progress, my dilemma and the possible openAPI spec structures I have jotted down

• After that, we moved on to further discussion on how to wrap up GET endpoints documentation properly, where a couple points arose

• First, handling the less common representations in the form of fullchildren for conceptResource for example, which was on a lesser priority but still on the ticket

• Another big priority was something known as search handlers, where we discussed at length how to refactor and change the files in order to make it more documentable because at its current stage, we can’t produce any readable documentation for it

• I was suggested to write a SearchHandlerParams class which the specified search handler used which had explicit typings which helped the documentation part become trivial at best, and this was kept for more analysis later

• For now, I was asked to clean up my code and make it presentable as I had written a lot of code, but it wasn’t really code reviewed properly apart from the files that my mentors had gone through

• I got to doing that, and I started changing the test file to occupy my new openAPI spec structure which took a while to debug and bring to ideal structure, but I was happy with the output

• Now, I was using Jackson ObjectMapper completely to make the JSON output, but I was asked to migrate to OpenAPI swagger-core so I could validate the structure created and make the creation process trivial, which I managed to do

• After that, I focused on a way to document the custom representation which was the most confusing decision I had to take yet

• In my pre-GSoC phase, I had written a schema introspector which using reflection could get any property that a given resource can access using the custom representation including the ones present in its superclass which was a very big win and a big reason for my selection in GSoC

• It was finally time I migrated that introspector in my standalone plugin, integrated its methods with my test file and used it to generate all properties and its types for all the representation properties we had

• It was a very big win, and after a lot of minute changes I was left with a spec that felt so accurate, and I couldn’t make it better even if I wrote it manually it works really well now

• Now I pushed all the code in my git repository and asked my mentors to code review it and started researching for the next problem we had

---

Challenges Faced

• To decide on the exact structure of the OpenAPI spec, there were multiple ways to go about it and each had their pros and cons, but I had to make a final decision based on what I thought was the best direction to take this project towards

• To integrate schema introspector logic inside the test context, making it work in the standalone plugin and using it to generate the custom properties and their types

• I have to find a way to decide how to make this plugin portable and module averse, as currently it completely depends on the REST module dependency inside the plugin’s pom.xml file

---

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

• Check 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 start working on the search handler’s logic and make it API documentation ready by refactoring the code or adding new logic

• Make a decision on where I want to take the plugin in terms of making it truly standalone or configurable and portable

• To participate in code review and bring up the project towards OpenMRS coding convention if any aren’t

---

Notes/Discussion Points

• This week in particular was very productive and I managed to generate a big part of the documentation, and I am really happy with the progress, hopefully I bring more good news in the coming weeks!

---

Thank you!