REST Web Services documentation not being generated/called

Hi all, I’m fairly new to OpenMRS development, having only been working on it for a few weeks on and off trying to get my head around things. I’m currently working on a module (probably just internal) and have been experimenting with the REST API documentation generator (might as well understand the framework properly in the process).

I’ve found the getGETModel and associated methods within the resource having looked at how its done in the webservices module, however these don’t appear to be getting called when outside this module. I think I’ve tracked it down to this if statement in the swagger creator, but I can’t see any logic behind it.

Having argued with maven I’ve got a build running without that statement and everything appears normal only now I’m getting my custom docs for extensions of DataDelegatingCrudResource, but still not for MetadataDelegatingCrudResource. I’ve submitted a help ticket to get access to the issue tracker to put a more technical issue in and then potentially submit a patch, but in the meantime I’m wondering if I’m missing something bigger.

1 Like

I think i agree with you on going ahead to create a ticket and raise a pull request. Thanks for the initiative. :slight_smile:

Looking at the code you shared above, it looked like the author encountered and exception and hence put a FIXME for somebody to look for a fix and remove the if statement. But @gayanw may have other thoughts :slight_smile:

I’ve found the getGETModel and associated methods within the resource having looked at how its done in the webservices module, however these don’t appear to be getting called when outside this module

getGETModel, getCREATEModel, getUPDATEModel for any resource are used by the SwaggerSpecificationCreator class of the webservices module.

I’m not sure about the FIXME. Maybe it is there from the beginning. It is not clear to me what your problem is. Can you share the source code for those resources that you want to appear in OpenMRS Swagger Documentation?

Have you seen https://wiki.openmrs.org/display/docs/Documenting+REST+Resources?

I would agree with you that it is the intention of the methods, and apart from the lines linked above it does appear to work as intended, however with those the calls to those methods in other modules are never made as they won’t start with org.openmrs.module.webservices.rest.

My problem specifically is that the methods are never called. I’ve created a test so I can step through it in the debugger and it just hits that return line every time. I also believe that to be the cause of all the swagger errors on the ref app API docs currently.

Sadly the project isn’t far enough along to have anything really sharable, at this stage I’m still experimenting with what might be possible so its extremely rough around the edges and not really committed in a sensible fashion yet (I really dislike committing new problems into code as they tend to stagnate).

1 Like

Sorry that it went unnoticed. Please work on a fix. Also, make sure that resources which are not in org.openmrs.module.webservices.rest are also handled properly.

Already worked on a fix, put RESTWS-721 in for further discussion around it beyond the obvious simply removing the check which does appear to work for everything.

@tomtom5152 on the ticket, can you include a link to this talk thread?

Added link

@tomtom5152 do you wanna work on it? :slight_smile:

Its a nice starting point for me for sure, whats the general contrib process, so far I’ve determined that tickets get prioritised and assigned by core members, but I’m unsure what happens from there on in. Is it just a case of forking on GH and submitting a PR linking back to the ticket?

Also for something like this, I’m trying to come up with an appropriate unit test at the moment (more for my own experience having come from a not Java background). As a guideline is this the sort of issue that requires a specific unit test?

You may take a look at this: https://wiki.openmrs.org/display/docs/Using+Git

And this: https://wiki.openmrs.org/display/docs/Pull+Request+Tips

Recommended practice is to start with a failing test and then fix the code to make it pass. :slight_smile:

1 Like