Wiki Spaces

Documentation
Projects
Resources

Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack

Projects

Page tree
Skip to end of metadata
Go to start of metadata

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 Unknown User (wyclif),

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

    Thanks

    Nyah

    1. Unknown User (wyclif)

      I update the page to include required skills

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

  3. Hello Unknown User (wyclif), 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. Unknown User (wyclif)

    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. Unknown User (wyclif)

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

  5. Unknown User (wyclif)

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

     

  6. Unknown User (bugembe)

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

    1. Unknown User (wyclif)

      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. Unknown User (wyclif)

    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. Unknown User (bugembe)

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

  8. Unknown User (wyclif)Unknown User (zakaria.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. Unknown User (zakaria.amine)

      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. Unknown User (wyclif)

    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. Unknown User (darius)

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

      1. Unknown User (wyclif)

        The work has already been merged

        1. Unknown User (darius)

          Has it been released?

          1. Unknown User (wyclif)

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