GSoD 2020 - OpenMRS REST API Documentation

Community Google Season of Docs
1

@ayesh

This is a new thread for discussing GSoD2020 REST API documentation.

4 Likes
2

Great we can continue here :slightly_smiling_face:

1 Like
3

@ayesh can you help me some starting points to research more on how to make examples of work, modifying the current documentation that we have.

Also the examples that are to be added in the documentation in different languages, they will just be an addition on the console right?? where currently only the curl examples are there .

4

@saurabh exactly they will be new tabs in the console.

Whag do you mean by work examples you can try out things with the demo server :slightly_smiling_face:.And make sure it works

1 Like
5

yess @ayesh like I can test the examples with the demo server and make sure it works but do we need something in the live documentation from where we can run those APIs ,

or we just need practical examples which can simply work and not the generic ones which we have in some examples now ? :slight_smile:

6

So I would say first add the new samples from Java and Javascript then we can think about having a live playground :slightly_smiling_face:

1 Like
7

@ayesh can you help me, whether I lookup on this for some insight on what resources might have been left out from the current documentation here

but the version mentioned in the psbrandt.io swagger based documentation is 1.11.6, (I dont know if that version corresponds to the APIs version or the document version itself) which is itself old since the github repo of openMRS webServices latest released version is 2.28.0.

thanks :smiley:

8

Hi @saurabh

Please refer the swagger doc here https://demo.openmrs.org/openmrs/module/webservices/rest/apiDocs.html

I think that one is little bit outdated

1 Like
9

thanks @ayesh :smiley:

10

Hi @burke I think @burke is here :smiley:

1 Like
11

yess @ayesh while searching through a bit of history on this project I got his extremely precise posts like these , which are really helpful in understanding a bit of buildup to this project !!

12

of course he is the project champion and my mentor as well as @batbrain7’s mentor last year :smiley:

1 Like
13

@ayesh I found this doc here what was it really used for ??

because it has the required tabs for other language examples but misses out on some resources that the current documentation has :slight_smile:

14

Oh, it was my playground prior to moving things to the openmrs repo. It just has the tabs nothing more.

I would prefer you to go through the slate docs to see how we can have tabs. Don’t refer to this one.

15

@ayesh ohkk I will do that thanks :slight_smile:

and a request @ayesh can you please review my PR here so that I can make suitable changes as suggested by @sanjula in addition to your suggestions. thanks

16

@saurabh I would like to suggest you now to work on the only missing resource we didn’t work on last time Forms resource. You can talk with developers refer the swagger documentation and other resources to get an idea.

1 Like
17

yes @ayesh , I will start working on forms next up surely !!

18

@ayesh as you requested on the github repo I started looking for resources on adding examples to in addition to the current cURL examples but I dint get a few things,

do we need examples of this format or we need plain http request examples which dont use annotations and rather simply create and http request to the OpenMRS webServices.

//generic example for uploading a resource

@RequestMapping(value = "/{resource}", method = RequestMethod.POST, headers = "Content-Type=multipart/form-data")
@ResponseBody
public Object upload(@PathVariable("resource") String resource, @RequestParam("file") MultipartFile file,
    HttpServletRequest request, HttpServletResponse response) throws IOException, ResponseException {
  baseUriSetup.setup(request);
  RequestContext context = RestUtil.getRequestContext(request, response);
  Resource res = restService.getResourceByName(buildResourceName(resource));
  if (res instanceof Uploadable) {
    Object updated = ((Uploadable) res).upload(file, context);
    return RestUtil.created(response, updated);
  } else {
    throw new ResourceDoesNotSupportOperationException(res.getClass().getSimpleName() + "is not uploadable");
  }
}
19

Hi @saurabh

So am talking about Forms in openMRS context if you refer https://demo.openmrs.org/openmrs/module/webservices/rest/apiDocs.htm You will be able to identify the forms resource. It has 2 subresources mentioned below.

  1. Resource
  2. Formfield

You have to first document this as we have done for other resources(patients, locations etc). as I mentioned previously then we can move to other types of examples like javascript, node.js.

Please remember this is all about finding things by engaging with the community you have all the required documents and resources. Please refer and come up with proper documentation for Forms :slightly_smiling_face:

1 Like
20

ohkk @ayesh I thought I had to do examples before this one :sweat_smile:

okay then I do forms before examples then!!.