Enhance the OpenMRS Swagger-based REST API documentation to add guidance on use of the API.
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.
See a sample of the auto-generated REST API documentation here.
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 forward.