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: https://qa-refapp.openmrs.org/openmrs/module/webservices/rest/apiDocs.htm
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.
https://issues.openmrs.org/images/icons/issuetypes/task.png RESTWS-562 – Improve Resource Definition Documentation - Closed
https://github.com/openmrs/openmrs-module-webservices.rest/pull/288
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:
"ModuleactionCreate": {
"type": "object",
"required": [
"action"
],
"properties": {
"allModules": {
"type": "string"
},
"action": {
"type": "string"
},
"modules": {
"type": "string"
}
},
New SPEC:
"ModuleactionCreate": {
"required": [
"action"
],
"properties": {
"modules": {
"type": "array",
"items": {
"type": "string",
"example": "moduleId"
}
},
"allModules": {
"type": "boolean"
},
"action": {
"type": "string",
"enum": [
"START",
"STOP",
"RESTART",
"UNLOAD"
]
}
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.
https://issues.openmrs.org/images/icons/issuetypes/task.png RESTWS-561 - Document Basic Search - Closed
RESTWS-561 Document Basic Search by gayanW · Pull Request #278 · openmrs/openmrs-module-webservices.rest · GitHub
https://issues.openmrs.org/images/icons/issuetypes/bug.png RESTWS-600 - Swagger documentation not correct for Encounter Search - Closed
RESTWS-600 Fix description of optional search params by gayanW · Pull Request #281 · openmrs/openmrs-module-webservices.rest · GitHub
There two are somewhat technical. So I’ll not try put them in simple context.
https://issues.openmrs.org/images/icons/issuetypes/bug.png RESTWS-614 - Formatter plugin in root pom configured with wrong javaCompilerVersion - Closed
https://issues.openmrs.org/images/icons/issuetypes/bug.png RESTWS-653 - Bad use of operations on String - Closed
https://issues.openmrs.org/images/icons/issuetypes/task.png RESTWS-560 – Create API Overview Docs - In Progress
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: default, ref, and full representations schemas for all the resources.
https://issues.openmrs.org/images/icons/issuetypes/newfeature.png RESTWS-568 – Optimize Swagger Spec Creation - In Progress
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.
Blog Posts
https://www.linuxdeveloper.space/tag/gsoc/ https://www.linuxdeveloper.space/getting-started-openmrs-sdk/
read more
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.
Thanks.