Swagger Documentations not generated for Resource subclasses.

samuel34 · January 7, 2019, 10:21pm

Hey,

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

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…

gayanw · January 9, 2019, 8:25am

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

github.com

openmrs/openmrs-module-webservices.rest/blob/813b0f2637112a5346d1392e37dedf73c8894612/omod-common/src/main/java/org/openmrs/module/webservices/docs/swagger/SwaggerSpecificationCreator.java#L710-L741


	private void addPaths() {
		// get all registered resource handlers
		List<DelegatingResourceHandler<?>> resourceHandlers = Context.getService(RestService.class).getResourceHandlers();
		sortResourceHandlers(resourceHandlers);
		
		// generate swagger JSON for each handler
		for (DelegatingResourceHandler<?> resourceHandler : resourceHandlers) {
			
			// get name and parent if it's a subresource
			Resource annotation = resourceHandler.getClass().getAnnotation(Resource.class);
			
			String resourceParentName = null;
			String resourceName = null;
			
			if (annotation != null) {
				// top level resource
				resourceName = annotation.name().substring(annotation.name().indexOf('/') + 1);
			} else {
				// subresource
				SubResource subResourceAnnotation = resourceHandler.getClass().getAnnotation(SubResource.class);

This file has been truncated. show original

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

samuel34 · January 9, 2019, 9:58pm

Thanks @gayanw. I believe this is the culprit

github.com

openmrs/openmrs-module-webservices.rest/blob/813b0f2637112a5346d1392e37dedf73c8894612/omod-common/src/main/java/org/openmrs/module/webservices/docs/swagger/SwaggerSpecificationCreator.java#L130


	 * Regenerate the swagger spec from scratch
	 */
	private void BuildJSON() {
		synchronized (this) {
			log.info("Initiating Swagger specification creation");
			toggleLogs(RestConstants.SWAGGER_LOGS_OFF);
			try {
				initSwagger();
				addPaths();
				addDefaultDefinitions();
				//				addSubclassOperations(); //FIXME uncomment after fixing the method
			}
			catch (Exception e) {
				log.error("Error while creating Swagger specification", e);
			}
			finally {
				toggleLogs(RestConstants.SWAGGER_LOGS_ON);
				log.info("Swagger specification creation complete");
			}
		}
	}

cc: @dkayiwa

samuel34 · January 10, 2019, 12:10pm

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

dkayiwa · January 10, 2019, 12:26pm

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

samuel34 · January 10, 2019, 12:27pm

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

gayanw · January 12, 2019, 6:44am

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.

sharif · January 15, 2020, 5:55am

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

sharif · January 15, 2020, 6:53am

Am reverting my statement,

	<dependency>
		<groupId>io.swagger</groupId>
		<artifactId>swagger-core</artifactId>
		<version>1.5.13</version>

finally found out the dependency