GSoD 2020 - OpenMRS REST API Documentation

Community Google Season of Docs
41

Some suggestions:

  • Perhaps edit the original post on this topic to include a link to the project page. Is it this page? If so, that wiki page appears to need an update.
  • It would be great to prioritize real world REST API documentation needs. I’ve heard some lately.
  • Is it possible to move examples alongside the corresponding documentation? For example, if you look at create person, the example comes after the documentation and appears to cause a blank space in the documentation to the left.
3 Likes
42

Thanks for the suggestions. I would like to see more code examples, use cases, workflows on API documentations, not just endpoints, requests and responses. The challenge is where and how to gather these information. You’ve given some good starting points. The format of the page can definitely be improved.

43

@burke How would you like to update this page?

44

@ayesh @burke @gcliff

I am trying to figure out how to generate java code for making an API call.
I found some code in controller test.
Could you please help in deciding whether these are usable in API docs? Thank you!

45

@ayesh I’ve figured out authentication code in java.Tested it, it worked. Will send a pr tomorrow. The rest should be easy. I hope. :slightly_smiling_face:

1 Like
46

@saurabh you can also have a look at this https://wiki.openmrs.org/display/docs/Documenting+REST+Resources

1 Like
47

@rainbow

Sure send a pr that would be easy :slightly_smiling_face:

48

@saurabh

Great lets finish off forms then move to what @burke mentioned :slightly_smiling_face: wqiting for youre pr review thanks

1 Like
49

yes @ayesh I have just pushed the changes after searching through the defintions and help by @gcliff :smiley:, i will move on to the things @burke suggested now !!

1 Like
50

Great will ask for @burke to review as well

In the mean time thanks alot @gcliff :slightly_smiling_face:.

3 Likes
51

@rainbow I think you might want to look at the SDK setup for OpenMRS so that you can use them to make your code samples and test them :slightly_smiling_face: !!.

52

@ayesh I fixed the formatting issue as suggested by burke here in this PR please review :smiley:

53

Thank you!

1 Like
54

@saurabh Looks like we both worked on the same files auth.md, vists.md etc. Will generate conflicts:sweat_smile:

55

@rainbow no problems I will resolve them and again push changes :sweat_smile:

56

Thank you very much! :slightly_smiling_face:

1 Like
57

@ayesh @burke For java requests, we can either just use plain java or we can use opemrs.SDK like what @saurabh suggested . But the benefit of using plain java code is the users don’t have to install anything other than jdk. There are benefits of using Openmrs.SDK as well. Do you have a preference?

58

@rainbow I think its better to use SDKs because they are designed for this purpose and if anybody wants to use OpenMRS webServices preferrably will first need to setup SDK so that work really gets simplified for that person and he dosent need to deal with all the things the devs have already abstracted to make life easier, also I looked up examples of various API documentations as well and they use their SDKs for presenting examples for sending requests and making API calls. :slight_smile:

1 Like
59

I have created a PR here which fixed that issue :slight_smile:

I have compiled a few resources from the openMRS wiki like this and about the global properties now being called as OpenMRS setting after the version 1.9 here .

@ayesh how do you think Global Property should fit in the documentation since we are having a segregation based mostly on resources , where do you think it should go !!

60

@saurabh sorry for the late reply. It looks great with the new formatting great work done.

And ofcourse global properties we should include in the docs. Based on property changes we have a lot work going on in plugins. Anything which helps developers should be there in the docs.

So I would suggest after Authentication section section in the docs @burke what do you think does that fit in there ?

1 Like