Our main objective was to improve the living documentation of the OpenMRS REST API, by improving its Swagger Specification and through improvements to how its Swagger Specification is being generated. All my code goes in the OpenMRS REST Web Services Module.
For those who are not familiar, it will be useful to have a quick look:
My GSoC Issues for the Summer
Below are the issues we’ve been tackling over the summer. I’ll try describe each in brief and the workarounds we’ve taken to solve them.
RESTWS-562 – Improve Resource Definition Documentation -
In our old spec, the datatype of properties are always string. But Swagger supports many different data types than just strings. So here we gave a complete revamp to the spec.
Old SPEC eg:
We have used swagger-core, its Java API and model classes as helpers to construct and generate the swagger json. As its being a radical redesign to the existing resource representations, this resulted in a mighty PR with about 102 file changes which gave me and my mentors a hard time
A sample swagger with the new changes can be found in here.
RESTWS-561 - Document Basic Search -
RESTWS-600 - Swagger documentation not correct for Encounter Search -
There two are somewhat technical. So I’ll not try put them in simple context.
RESTWS-614 - Formatter plugin in root pom configured with wrong javaCompilerVersion -
RESTWS-653 - Bad use of operations on String -
RESTWS-560 – Create API Overview Docs -
The issue suggests that we add an overview to the existing swagger documentation (on top of the swagger-ui itself), so that it helps API user understands concepts such as OpenMRS’ resource representations, how to perform authentication and the like. However the idea behind swagger-ui is to make any API self explanatory, so no more guidance should be needed for the user. So my suggestion was that we simply upgrade the swagger-ui which my mentors also agreed with.
This also gives us the ability to show all:
full representations schemas for all the resources.
RESTWS-568 – Optimize Swagger Spec Creation -
Simply put, now the swagger spec will be generated only once every context refresh, instead of having to repeat the process of regenerating the spec each and every web request, we serve a cached copy.
My Experience with OpenMRS
First of all I'm beyond thankful to Shreyans (@bholagabbar) my mentor for giving me this opportunity. It has been a pleasure working with you. I look forward to continuing to see you around and hopefully we could continue the work that we have started.
I'd also like to thank @pascal, @dkayiwa and all the community members for all the hard work they've put in to help me get things done. It's being an amazing experience. Hoping to work with you all for the years to come.
Suggestions for Making the Program Better
I think, improving the documentation could help as there seems to have outdated content here and there. I can't think of anything In particular other than that. You people have handled this program exceptionally well, I believe.