GSoC 2017 - Improved REST API Documentation Project - Final Presentation

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 :slight_smile:

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.

6 Likes

Thank you for your contributions @gayanw :). Keep up your good work.

1 Like