# GSoD 2020 - OpenMRS REST API Documentation **URL:** \ **Category:** Google Season of Docs\ **Created:** [May 28, 2020, 2:44pm UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736 "2020-05-28T14:44:55Z")\ **Posts on this page:** 20\ **Page:** 10
**Author:** ![saurabh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/saurabh/32/11527_2.png) [@saurabh](https://talk.openmrs.org/u/saurabh)\ **Post date:** [August 19, 2020, 2:15pm UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/181 "2020-08-19T14:15:59Z")
ohk @ayesh I will come up with a timeline based on this and get it reviewed again 🙂 ---
**Author:** ![ayesh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ayesh/32/10674_2.png) [@ayesh](https://talk.openmrs.org/u/ayesh)\ **Post date:** [August 19, 2020, 2:19pm UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/182 "2020-08-19T14:19:49Z")
cool that is great ---
**Author:** ![saurabh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/saurabh/32/11527_2.png) [@saurabh](https://talk.openmrs.org/u/saurabh)\ **Post date:** [August 20, 2020, 2:50pm UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/183 "2020-08-20T14:50:14Z")
@ayesh I have made a broad time division, I will make changes to them as per suggestions and then would add details for each time division in the table. > **[Extending User Friendly Github Documentation for REST API](https://docs.google.com/document/d/1gizOcmNQvsqiunRNAPV2kLiAO-BWFC9i74ayl_yjZgU/edit?usp=sharing)** > > OpenMRS API Documentation Extending User Friendly Github Documentation for REST API Project Proposal for Google Season of Docs 2020 Mentors: Ayeshmantha Perera Burke Mamlin Saurabh kumar ... ---
**Author:** ![herbert24](https://talk.openmrs.org/user_avatar/talk.openmrs.org/herbert24/32/8178_2.png) [@herbert24](https://talk.openmrs.org/u/herbert24)\ **Post date:** [August 21, 2020, 8:02am UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/184 "2020-08-21T08:02:41Z")
Thanks @saurabh ---
**Author:** ![ayesh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ayesh/32/10674_2.png) [@ayesh](https://talk.openmrs.org/u/ayesh)\ **Post date:** [August 21, 2020, 11:42am UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/185 "2020-08-21T11:42:42Z")
Hi @saurabh First I would like you to create a survey. It will be great if you can come up with that during the community bonding period as @rainbow did. This will help us to identify what we are missing in the documentation which will be useful for developers and other users. It’s good if you can come up with set of questions which will help us to identify these issues. I added a rough estimation for the time line in you’re doc that can vary during the project time. Let’s discuss about that later. The survey is something we should focus during this period because last time also we didn’t get much feedback on the docs. Bu I think it is good if we can move forward with the feedback from the community it will help us to identify what we actually need to do. ---
**Author:** ![saurabh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/saurabh/32/11527_2.png) [@saurabh](https://talk.openmrs.org/u/saurabh)\ **Post date:** [August 21, 2020, 11:46am UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/186 "2020-08-21T11:46:52Z")
sure @ayesh I will take @rainbow 's help in this and float a survey within the community bonding period and after that in the middle of the project as you indicated in the google docs. thank you for the suggestions on the timeline 🙂 ---
**Author:** ![ayesh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ayesh/32/10674_2.png) [@ayesh](https://talk.openmrs.org/u/ayesh)\ **Post date:** [August 21, 2020, 11:49am UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/187 "2020-08-21T11:49:49Z")
Yes that will be great. Actually lets not think about the time line for now. Lets see how the survey results going to be. Make sure to include a section in the survey to inform what are the tasks we are focusing on this project.And it will be good if the developers can give us an idea which order we should follow on achieving these tasks. ---
**Author:** ![saurabh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/saurabh/32/11527_2.png) [@saurabh](https://talk.openmrs.org/u/saurabh)\ **Post date:** [August 21, 2020, 11:51am UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/188 "2020-08-21T11:51:05Z")
yes @ayesh that would be great then we would be able to prioiritize our tasks and make a timeline accordingly. ---
**Author:** ![ayesh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ayesh/32/10674_2.png) [@ayesh](https://talk.openmrs.org/u/ayesh)\ **Post date:** [August 21, 2020, 11:52am UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/189 "2020-08-21T11:52:05Z")
exactly 😃 ---
**Author:** ![burke](https://talk.openmrs.org/user_avatar/talk.openmrs.org/burke/32/17_2.png) [@burke](https://talk.openmrs.org/u/burke)\ **Post date:** [August 21, 2020, 5:48pm UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/190 "2020-08-21T17:48:27Z")
@saurabh & @ayesh, hopefully you’re seeing conversations [like this one](https://talk.openmrs.org/t/mismatch-between-the-rest-api-swagger-and-manual-documentation-which-is-which/29949). I would recommend focusing on the human-readable content & examples (the content we don’t get from a tool like Swagger), assuming we will eventually want to combine this content with auto-generated information from our code (or even move this content into the code so full documentation can be auto-generated). In other words, I would not spend a lot of time manually generating what can be automatically generated from code using tools like Swagger; rather, focus on the information a developer needs to effective understand & use the API. Ultimately, we’d like to be able to merge human written documentation and auto-generated documentation that is relatively easy to keep in synch with the code and goes beyond a simple enumeration of resources with little guidance on how/why/when to use them. ---
**Author:** ![ayesh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ayesh/32/10674_2.png) [@ayesh](https://talk.openmrs.org/u/ayesh)\ **Post date:** [August 21, 2020, 5:57pm UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/191 "2020-08-21T17:57:28Z")
Hi @burke Yes I think that will be great. Because code snippets we can actually generate from openAPI easily. What we need to focus is much on the how/why/when to use them. Any starting point for moving forward would be great @burke. I really appreciate if we can have some inputs from you regarding what we can achieve from the project in this phase. ---
**Author:** ![saurabh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/saurabh/32/11527_2.png) [@saurabh](https://talk.openmrs.org/u/saurabh)\ **Post date:** [August 21, 2020, 6:10pm UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/192 "2020-08-21T18:10:10Z")
@ayesh I think @burke is emphasising on the part that we should be focused more on code snippets and more descriptive content which we dont get from swagger.( something like we have in github documentation) like describing each param and resource in a human readable way with some usage context. I would definitely add a suggestion block in the survey, I am currently working upon to get more views like these 🙂 ---
**Author:** ![ssmusoke](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ssmusoke/32/8020_2.png) [@ssmusoke](https://talk.openmrs.org/u/ssmusoke)\ **Post date:** [August 22, 2020, 9:16am UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/193 "2020-08-22T09:16:55Z")
@saurabh @ayesh I would suggest the following approach which blends both needs 1. Improve the speed of generation and quality of the generated docs - need to update from Swagger to OpenAPI? 2. Embed example data and code snippets 3. Look into generating the documentation and pushing it to a 3rd party hosting system - IMO even GitHub pages is good enough (can use a custom domain) ---
**Author:** ![saurabh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/saurabh/32/11527_2.png) [@saurabh](https://talk.openmrs.org/u/saurabh)\ **Post date:** [August 22, 2020, 9:31am UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/194 "2020-08-22T09:31:08Z")
@ssmusoke great suggestions, but I think as far as the project description we dont want to go back to the dynamically generated docs rather we moved on from the swagger based documentation and we are planning to embed that swagger based documentation to the current static github documentation, so that we could provide a try out feature to the people and the static documentation would serve as a source of concise and helpful examples and description about resources. ( examples in the static documentation might not be as exhaustive making use of all the parameters since our aim is to provide a good starting point to understand the endpoint and we can do any amout of experimentation in the swagger based try out feature, though the parameter description of each resource covers all those params exhaustively ) ---
**Author:** ![ssmusoke](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ssmusoke/32/8020_2.png) [@ssmusoke](https://talk.openmrs.org/u/ssmusoke)\ **Post date:** [August 22, 2020, 12:17pm UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/195 "2020-08-22T12:17:19Z")
@saurabh Sorry I am late to the game, I am wondering why the automatically generated documentation is being discarded in favor of manually edited documentation, which I can guarantee will have a large gap even in the next 3 to 6 months If you look at the issue I am facing, the manual documentation has lots of gaps, including a large mismatch already or maybe I am missing something > [@Mismatch between the REST API Swagger and Manual Documentation - which is which](https://talk.openmrs.org/t/mismatch-between-the-rest-api-swagger-and-manual-documentation-which-is-which/29949): > > I am having a hard time correlating which documentation is correct and which one should be followed. For example when creating an encounter the bundled documentation in OpenMRS shows this { "patient": { "person": "uuid", "identifiers": [{ "identifier": "string", "identifierType": "uuid", "location": "uuid", "preferred": true }] }, "encounterType": { "name": "string", "description": "string" }, "encounterDatetime": "str… ---
**Author:** ![burke](https://talk.openmrs.org/user_avatar/talk.openmrs.org/burke/32/17_2.png) [@burke](https://talk.openmrs.org/u/burke)\ **Post date:** [August 22, 2020, 2:19pm UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/196 "2020-08-22T14:19:04Z")
> [@ssmusoke](#): > > I am wondering why the automatically generated documentation is being discarded in favor of manually edited documentation @ssmusoke, the goal isn’t to discard the automatically generated inventory of resources, but to improve on it. I would like to see decent documentation of key parts of the API (primarily key pieces: authentication, concepts, patient, visit, encounter, obs) that we all agree is top notch and that all devs (new & seasoned) find useful. At this point the manual documentation and auto generated documentation both have faults/gaps. If you can help us get the manual documentation in excellent shape for these few key resources, then we can strategize how to expand that goodness to all resources and make it sustainable. ---
**Author:** ![saurabh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/saurabh/32/11527_2.png) [@saurabh](https://talk.openmrs.org/u/saurabh)\ **Post date:** [August 23, 2020, 11:02am UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/197 "2020-08-23T11:02:18Z")
@ayesh I am almost done with the form could you please look up the form once and suggest some changes, after which I will post it in Talk for all the community members 🙂 ---
**Author:** ![burke](https://talk.openmrs.org/user_avatar/talk.openmrs.org/burke/32/17_2.png) [@burke](https://talk.openmrs.org/u/burke)\ **Post date:** [August 23, 2020, 2:09pm UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/198 "2020-08-23T14:09:28Z")
In the form, do you show an example of our best documented resource and ask them what they like and what they don’t like about it? Do you ask them for an example (URL) of what they consider best of class REST API documentation? ---
**Author:** ![saurabh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/saurabh/32/11527_2.png) [@saurabh](https://talk.openmrs.org/u/saurabh)\ **Post date:** [August 23, 2020, 2:29pm UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/199 "2020-08-23T14:29:35Z")
Sure great suggestions @burke added 🙂 ---
**Author:** ![ayesh](https://talk.openmrs.org/user_avatar/talk.openmrs.org/ayesh/32/10674_2.png) [@ayesh](https://talk.openmrs.org/u/ayesh)\ **Post date:** [August 23, 2020, 8:31pm UTC](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736/200 "2020-08-23T20:31:40Z")
Yes I think both swagge and the rest doc seems to be having problems which we must try to fill as @burke mentioned. Let’s go one by one @saurabh Can you share the survey link here we can get @burkes and @ssmusokes suggetions before sharing it with the community 🙂 [Previous page](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736.md?page=9) [Next page](https://talk.openmrs.org/t/gsod-2020-openmrs-rest-api-documentation/28736.md?page=11)