Swagger Documentations not generated for Resource subclasses.


What I’m working on!

I’m currently working on IDGEN-24 which is now considered as a community priority ticket.

Work done : Added the identifier source resources to idgen module.

Impending : Documenting these subclass resources.

Issue (Current Blocker)

Following this clear and intuitive doc on documenting REST resources, it clearly states how to make sure your newly introduced Resources are added to the Swagger docs. Well nice catch, this worked for my case on all @Resources and @SubResources but failed for all @SubClassResourceHandlers. Well just to be sure I did the right thing, let me explain what I did.

Let me use the IdentifierPool as an example a SubClass of IdentifierSource. I added it’s handler then overriden these methods. But its subclassresource wasn’t added in the docs.

Justification that the bug is real :smile:

Well in the webservices.rest module, we have the Drug resource which has subclassresources like DrugOrder which has a handler where the required methods are also overridden here. I setup a server running the supported openmrs version for these resources but Drug Resource and its Subresources appear but not it’s subclasseresources. I have investigated this for a while.

Could I be missing something? Can someone with a better insight help me!

cc: @dkayiwa, @gayanw, @burke Thoughts…

1 Like

@samuel34 The method below handles the process of generating swagger paths for the registered resource handlers.

I don’t have an OpenMRS instance to test things out. I hope this will help debug, and find a solution to the problem.

1 Like

Thanks @gayanw. I believe this is the culprit

cc: @dkayiwa

Created issue : https://issues.openmrs.org/browse/RESTWS-748

Did you confirm that we do not have any existing sub resource generated here? https://qa-refapp.openmrs.org/openmrs/module/webservices/rest/apiDocs.htm

Yes and FYI I’m talking about subclasses not subresources @dkayiwa

addSubclassOperations method is introduced in the commit.

@samuel34 I remember that I did comment out the call to that method because it seems to only handle the POST operation. Unfortunately, I’m having a hard time testing it out on my machine because of some performance reasons. You may try out uncommenting the method call to see how things show up in the doc.

Maybe @pascal have insights on what needs to be improved in addSubclassOperations method.

Thanks all for great work, While am working on this ticket, https://issues.openmrs.org/browse/RESTWS-720, would like to know which java framework libraries in openmrs do we use for swagger documentation, in the first case we can use either https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 or any other Personally tried to look into pom to see which swagger library being used in openmrs webservices.rest but could not see the dependency.Another idea could be creating a doclet initialiser of which this would require spring libraries like springfox for configuration. @samuel34, @dkayiwa any help about coming up with this thanks

Am reverting my statement,


finally found out the dependency :slightly_smiling_face: