Page Comparison

Primary Objective

Enhance Extend the OpenMRS Swagger-based REST API documentation to add guidance on use of the APIexisting User-Friendly GitHub Documentation for Rest API project.

Project Description

The OpenMRS REST API is one of the key mechanisms for developers to access data from OpenMRS. We have used Swagger to create auto-generated documentation of the API.

Users of the documentation struggle to understand how to use the REST API and usage of OpenMRS web services are harder than necessary. There are times when users try to  seek guidance on the OpenMRS Talk forum and often the solutions are captured on that platform but not consolidated or updated. . Our auto-generated Swagger documentation provides nice scaffolding for documentation, but doesn’t provide the context, tips, and easy read that those richer API docs (weaving human documentation alongside swagger-like documentation) provide.

With the help of a documentation expert we hope to establish a well structured page which is easy to follow  such as GitHub API documentation, Twitter API documentation, or the Google Maps API documentation. At the conclusion of the project we hope to have a format and approach that could be replicated for all modules on OpenMRS moving forwardIn the last year with GSoD, we developed a user-friendly GitHub documentation. Which can be found hosted in this URL

The purpose of this project is to come up with documentation for the missing resources and add more examples (Currently we have only curl example add Javascript, Java examples).

The final goal is to make the documentation a playground for the newcomers to get an idea about the current resources we have in openMRS.

You can find the repository for the project here  (As you can see the build is failing to fix it would be a good starting point to get an idea how things work with the static content server used underneath).

Skills Needed

• Possess knowledge in how to structure user documentation for use by different types of users, not only developers or people with technical know-how.
• Experience in software engineering, infrastructure engineering, knowledge of how REST API works.
• Comfort with working with GitHub repositories.
• Great communication skills.

Objectives at the end of the Assignment :

...

• Find the missing resources ( There won't be much uncovered but there should be at least one or two).
• Try out the current curl examples make sure they're up to date.
• Come up with Java & Javascript examples.
• Finally, make sure to present the progress weekly with a talk post which will help to get the feedback from the community.
• It will be good if we can make examples of work with the demo OpenMRS server which means anyone should be able to execute example from the documentation site.

Related Resources

• Old (outdated) documentation: REST Web Service Resources in OpenMRS 1.9
• Sample Swagger documentation: https://psbrandt.io/openmrs-contrib-apidocs/
• Last year final review blog: https://medium.com/@ayeshmanthaperera/gsod19-openmrs-4259aa6356f1