Have you implemented OpenMRS? Please participate in the Implementation Site Survey. If you already have, thank you!
Child pages
  • REST Documentation Generator Project
Skip to end of metadata
Go to start of metadata

Primary mentor

Wyclif Luyima

Backup mentor

Rafal Korytkowski

GSoC student

Zakaria Amine

Background

Webservices.rest is probably the most actively developed and used module in OpenMRS. It is a part of the OpenMRS platform and is bundled with each new release. It provides REST API for OpenMRS, which is used by modern UIs and external services. Currently most of its documentation is auto-generated, but it does not cover all exposed features. The goal of this project is to make the REST documentation generator more robust and easier to use.

Objectives

  1. Implement a tool to extract and generate documentation for SearchHandlers. A list of supported parameters is provided by developers in SearchConfig, which is a required field of every SearchHandler.
  2. The documentation should be improved to list differences in resource representations or available search parameters based on installed OpenMRS version or modules.
  3. Implement a way for developers to document any field of a resource. The provided documentation should be extracted and put in the auto-generated documentation. See DelegatingResourceDescription.
  4. Add a way to export the generated documentation in wiki format directly from the running module by going to Administration -> REST Web Services -> Help.
  5. (Alternative to 4. is to consider adopting something like http://swagger.io/ or whatever is used by https://openmrs.github.io/openmrs-contrib-modulus/ to make the docs look better and easier to consume)

Skills Needed

  • Decent Java coding skills
  • Ability to work with minimal supervision

Resources

  1. Webservices.rest 
  2. REST Web Service Resources in OpenMRS 1.9
  3. Old documentation creator

19 Comments

  1. Hello Wyclif Luyima,

    I will like to know the skill sets required for this project?

    Thanks

    Nyah

    1. I update the page to include required skills

  2. Thanks, because I plan on submitting a proposal for this project too.

  3. Hello Wyclif Luyima, I am currently working on a proposal for this project. With my prior development experience, I believe I can handle this with minimal supervision and I will share it with you to get your feedback and comments.

    Cheers!

  4. That is good! Thanks for the interest, i think we should not use this as a communication media, let's only use this for comments about the project and let's use the other OpenMRS communication media like talk.openmrs.org for any other communication. As i mentioned earlier, you need to add your application to milange and you will get feedback from reviewers if more is needed.

     

    1. They are not yet accepting applications on milange, but they should be within the next 2weeks

  5. Nyah Check I will be happy to discuss design issues around the project on talk.openmrs.org

     

  6. Hello Wyclif Luyima. I am interested in this project though my Java skills are intermediate. Am I eligible to take it on?

    1. For general questions, try to use talk.openmrs.org instead of posting here, let's leave this page for design related discussions about the project

      1. @Wyclif I have finished working on my proposal for this project. I'll like to get your feedback and comments on modifications I could make to make it better. I'll move on to finishing the ticket I'd started working on. I created a thread on talk for that.

  7. Doing some OpenMRS tickets will help you polish up your skills and will help the people that review the applications to determine if you are a good fit, have you tried any?

    1. Okay. Am learning how to do them. Thank you very much.

  8. Wyclif LuyimaZakaria Amine,

    It looks like this project page never got progress updates. I found the midterm presentation on Talk, but where can I find status/demo of REST documentation? Did we get any closer to having interactive REST documentation (e.g., Swagger) via a module in the reference application?

    1. Hi Burke, 

      As Wyclif mentioned, we are still working on merging the work with the base module. In the meanwhile you can give it a try by uploading this intermediary version ( which does not include master branch recents commits, but works fine) : https://drive.google.com/file/d/0B4Sn8X-cz8IzRVFiQXJZbC1Wcmc/view?usp=sharing

  9. We are using swagger to render the documentation , Daniel is in the process of merging the work into the master branch and release it with platform 1.11.4

     

    1. As far as I can tell this work was not included in the Platform 1.11.4 release. What is the current plan?

      1. The work has already been merged

        1. Has it been released?

          1. No version of the module has been released yet since the merge