GSoD 2020 - OpenMRS REST API Documentation

Community Google Season of Docs
201

thanks @burke @ayesh @saurabh @ssmusoke for all the inputs on this!

1 Like
202

sure @ayesh the form can be accessed here

1 Like
203

Hi @burke @ssmusoke

@saurabh has shared the survey here.It will be really helpful for us to idnetify the missing parts if you have a look on it

Thank you

1 Like
204

@ayesh @burke @ssmusoke if the form looks good should I open the form for the community’s feedback, I will create a seperate post for it and link the post here .

1 Like
205

When I went for a last minute review of the form, I was greeted by a message saying “The form OpenMRS Rest API documentation Survey is no longer accepting responses. Try contacting the owner of the form if you think this is a mistake.”

206

@burke but I havent yet made the form open for accepting responses I thought I will do that after making it public on the talk

207

I made it open for accepting responses now !!

208

@saurabh, overall it looks good.

I’d consider making the first question optional. People may have useful feedback for you but not want to take the time to fill out a priority grid.

For me, the first question is hard to answer, because what I consider to be high priorities aren’t in the list. From my perspective, the approach would be something like:

  1. Documentation developers can count on for the basics & most commonly used parts of the API (e.g., authentication, patient, encounter/visit, obs) with helpful, concise documentation, good descriptions, and examples that work.
  2. Clean up issues with existing documentation (typos, broken links, “parroting” descriptions like foo’s bar property described as “Bar of the foo”, etc.), especially for resources in #1.
  3. Using output from #1 & #2 as our “north star” (exemplars of ideal documentation) to inform changes needed in source code so that we can auto-generate useful documentation for those resources.
  4. Updating source code annotations based on findings in #3, so we have decent auto-generated documentation.
  5. Creating/fixing a Maven task to generate Swagger documentation that can be woven together with static documentation to generate the content that we can host at rest.openmrs.org and could be built into the REST module to be served up in place of the current Swagger documentation.
  6. JS examples.
  7. Expand to more resources.
  8. Interactive examples.

In any case, don’t let perfect be the enemy of good
 announce your survey in the dev category of Talk as soon as you have @ayesh’s approval. :slight_smile:

2 Likes
209

@burke thanks alot for the valuable feedback. I would agree on the priority of the list and it make sense to move forward on that way.

@saurabh I would suggest you to do the changes burke mentioned. Let’s publish it as soon as the changes are done.

Also great work on bringing up the survey so fast. Nice work @saurabh

1 Like
210

@burke @ayesh I am bit unclear about #3, #4

I get #2, we would dive deep into those basic resources and try to get as close to the ideal documentation as possible .

Then I am a bit unsure what do we do in #3 and #4, try and get those changes incorporated in the swagger auto generated documentation by editing the OpenAPI spec or any anything else I dint get ? or try and expand the work done to other resources.

Then in #5 we embed the auto-generated documentation (after going through #3 and #4) in our static documentation which would even give us a try-out-feature in our static documentation.

211

I think the current Swagger documentation may be built through real-time queries to the API. While this sounds like the coolest & most robust approach to ensuring resources are properly represented, the reality leaves a lot to be desired. First, there’s an undesirable delay to regenerate the documentation every time it’s referenced, making the real-time generation less than ideal. Secondly, the auto-generated properties are often not what we’d want (e.g., all the details for a location instead of just the UUID as reference). Lastly, the datatypes are under-specified and description are lacking in many/most cases.

That said, I was hoping/expecting that we could use a Swagger/OpenAPI tool to generate an OpenAPI document from comments/annotations in the code. If true, then the task ahead would be to go through those annotations/comments and populate them so we can generate documentation similar to #2.

1 Like
212

I will do a bit of research about it and see how would it work but currently I will add these to the google form :slight_smile:

1 Like
213

@saurabh yes when moving forward let’s try to find a way and do it together. For now, let’s get feedback from the community.

1 Like
214

the survey is up :smiley:

215

nice :smiley:

cc :- @jennifer @grace @herbert24 we need some help here to get responses to the survey.

216

Good job, @saurabh. I made a few tweaks to your post. I hope that’s okay. :slight_smile:

2 Likes
217

@ayesh @burke,

just a thought since we find it difficult to make examples that actually work at an instance since sometimes the UUID used in the examples arent present on the server.

  1. we can shift the create Resource section above the list resource section in every resource heading and that way we would be able to use the UUID of the created resource for listing, editing and deleting .

  2. sometimes in complex resources there is a requirement of other resources’ UUID as well, in this case we might need to make some resources read-only on the server so that they cant be deleted and can be used in the examples safely.

(I have seen instances of such resources while creating examples for system setting here and I had mentioned there that we must create our own system setting in order to modify it because some of them are read-only)

218

@saurabh,

I would suggest using UUIDs for data provided in the default demo dataset. The demo dataset SQL is here. The easiest way to play with the demo data at the moment is to use Docker:

  1. Copy this docker-compose.yml file into a local folder,
  2. Place this SQL file into a dbdump subfolder
  3. Type docker-compose up -d in the original folder (containing the docker-compose.yml file)

Within a few minutes, you should have OpenMRS with demo data starting up locally at http://localhost:8080/openmrs/ and, when it’s done, you can login using admin/Admin123 credentials. You can also test the API using httpie:

$ http localhost:8080/openmrs/ws/rest/v1/session
HTTP/1.1 200 OK
Content-Length: 70
Content-Type: application/json;charset=UTF-8
Date: Fri, 28 Aug 2020 15:49:38 GMT
ETag: "0c4da90337cfeb79674b823f8e4c42e47"
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=A5CD4820FD7BBD22ECC1DFC58758E49C; Path=/openmrs; HttpOnly

{
    "authenticated": false,
    "sessionId": "A5CD4820FD7BBD22ECC1DFC58758E49C"
}

p.s. You can stop and start OpenMRS with docker-compose stop and docker-compose start (takes a few minutes to restart). You can clean up (remove everything) with docker-compose down -v (you’ll have to go through full initialization process the next time you bring it up).

1 Like
219

@burke I will try setting this up thanks :slight_smile:.

if developers try these examples on the demo -server will these examples still work? since I think people can purge some of the resources present on the server.

220

tl;dr true, but I wouldn’t worry about it

Correct, but I don’t think this is a big enough problem to worry about. If we end up with issues of people routinely purging data on the demo server, we can either try pointing our examples to different resources (e.g., if we happened to pick resources that are more commonly purged on demo) or consider making some data read only on demo. I don’t think this is going to be enough of an issue to warrant the effort.

A more likely issue is demo being down, but I think that will be less of a problem over time as we improve our dockerization and by adapting demo to use an image that has already performed initialization.

1 Like