Here ends the third week. My focus this week is to work on the task RESTWS-562 – To Improve Resource Definition Documentation
I’ll try explain RESTWS-562 in brief. Swagger Doc (aka Spec, or just Swagger Json) of OpenMRS is generated programmatically. Typically Swagger Spec of an API is generated just by annotating its resource classes and their corresponding operations which is no big deal. A library such as swagger-core would then take care of automating the generation of the spec. For a while. I was wondering why OpenMRS have decided to do it the other way around, to generate the spec file manually. Though it has its own advantages, such as not having to go through annotating every other resource, it does require the need to deal with some advanced techniques such as Java Reflection and have to duplicate some of the work already done by other libraries.
Talk thread here finally answers my doubt. Rest API of OpenMRS does not have one to one mapping with its Java API. So a Swagger model formed by directly serializing a Java class may not be the actual representation of that API resource. So some kind of manual serialization of resources is required.
I’ve been writing test cases to see the different possibilities before begin the actual implementations. It’s being really beneficial, because I could test changes without actually having to restart the OpenMRS server which eliminates the need to compile and restart. I’ll be using swagger-core as a helper library. And hope to make the code more concise and elegant as possible.