RESTWS-980: Initial implementation of OpenAPI Generator Maven Plugin with JavaParser integration #657

capernix · 2025-05-20T17:16:25Z

Description of what I changed

Introduced a new OpenAPI Generator Maven Plugin that integrates JavaParser to extract Javadoc from OpenMRS REST resource classes. This initial implementation serves as a proof-of-concept for enhancing OpenAPI documentation with descriptive information from source code.

Key Implementation Details:

Created a custom Maven plugin (openapi-generator-maven-plugin) with JavaParser integration
Implemented source file location logic to find Java classes across module source roots
Added functionality to parse Java source files and extract class-level Javadoc comments
Successfully tested extraction of Javadoc from PatientResource1_8 class
Fixed a Maven build dependency issue by moving the unpack-dependencies goal from generate-resources to prepare-package phase

This implementation provides the foundation for programmatically enhancing API documentation by leveraging the existing Javadoc in the codebase.

PS: I also pushed the code for the schema introspector alongside so the work can be combined in future commits.

Issue I worked on

https://openmrs.atlassian.net/browse/RESTWS-980

Checklist: I completed these to help reviewers :)

[x] My IDE is configured to follow the code style of this project.

No? Unsure? -> configure your IDE, format the code and add the changes with git add . && git commit --amend
[] I have added tests to cover my changes. (If you refactored
existing code that was well tested you do not have to add tests)

No? -> write tests and add them to this commit git add . && git commit --amend
[x] I ran mvn clean package right before creating this pull request and
added all formatting changes to my commit.

No? -> execute above command
[x] All new and existing tests passed.

No? -> figure out why and add the fix to your commit. It is your responsibility to make sure your code works.
[x] My pull request is based on the latest changes of the master branch.

No? Unsure? -> execute command git pull --rebase upstream master

mherman22 · 2025-05-25T08:52:43Z

tools/openapi-generator-maven-plugin/pom.xml

+
+    <groupId>org.openmrs.plugin</groupId>
+    <artifactId>openapi-generator-maven-plugin</artifactId>
+    <version>1.0-SNAPSHOT</version>


@capernix i know this is still in draft but have a look at how versioning is done in OpenMRS, -> https://openmrs.atlassian.net/wiki/spaces/docs/pages/25477712/Versioning

I'll take a look thanks

capernix · 2025-06-18T07:08:05Z

About the Commit: Enhanced the Plugin to invoke the required function and parse representations

Created a Maven Plugin that currently sets up the URLClassLoader, tests if Rest Constants are accessible, loads the specific resources and invokes getRepresentationDescription() to gather all the properties of the resource.

mherman22 · 2025-06-18T08:12:18Z

tools/openapi-generator-maven-plugin/src/main/java/org/openmrs/plugin/OpenAPIMojo.java

+    @Parameter(defaultValue = "${project}", required = true, readonly = true)
+    private MavenProject project;    @Override
+    public void execute() throws MojoExecutionException, MojoFailureException {
+        getLog().info("=== OPENAPI GENERATION STARTED ===");


I would prefer you declaring something like private static final Logger logger = LoggerFactory.getLogger(OpenAPIMojo.class); and replace this line with something like logger.info(.....);

Do the same for all your logging needs

tools/openapi-generator-maven-plugin/src/main/java/org/openmrs/plugin/OpenAPIMojo.java

mherman22 · 2025-06-18T08:34:37Z

omod-1.8/pom.xml

 				<groupId>com.mycila</groupId>
-				<artifactId>license-maven-plugin</artifactId>
-				<configuration>
+				<artifactId>license-maven-plugin</artifactId>				<configuration>


Is this change part of your plugin implementation?

mherman22 · 2025-06-18T08:35:31Z

omod-1.8/pom.xml

+			<plugin>
+				<groupId>org.openmrs.plugin</groupId>
+				<artifactId>openapi-generator-maven-plugin</artifactId>
+				<version>1.0-SNAPSHOT</version>


This versioning doesnt match openmrs' style of versioning, look at https://openmrs.atlassian.net/wiki/spaces/docs/pages/25477712/Versioning

...a/org/openmrs/module/webservices/rest/web/v1_0/controller/SchemaIntrospectionController.java

chibongho · 2025-06-21T03:27:55Z

tools/openapi-generator-maven-plugin/pom.xml

+
+    <dependencies>
+        <!-- Maven Plugin API -->
+        <dependency>


I see classLoader.loadClass used quite a bit to load classes from the rest module. Does it make sense to just make it a dependency so we can use those classes directly?

I'll try this out and get back

chibongho · 2025-06-21T03:33:34Z

tools/openapi-generator-maven-plugin/src/main/java/org/openmrs/plugin/OpenAPIMojo.java

+        }
+
+    } catch (Exception e) {
+        getLog().error("Method invocation failed: " + e.getMessage());


Avoid this catch-and-log pattern. It hides the stack trace. If the error is unrecoverable, just let it be thrown without catching.

Also, try to avoid catching Exception, as it is too general. You might mask genuine coding errors like IndexOutOfBoundsException.

chibongho · 2025-06-21T03:43:43Z

tools/openapi-generator-maven-plugin/src/main/java/org/openmrs/plugin/OpenAPIMojo.java

+        Class<?> resourceClazz = loadClass(TARGET_CLASS_NAME);
+
+        // Test PatientResource instance creation
+        testPatientResourceInstantiation(resourceClazz);


Are we ready to make this work for all Resources classes?

According to my observations and testing, almost all of the resource files are working perfectly.
But an exception I found was ConceptResource1_8 that has it's full representation in a different method than getRepresentationDescription(), and it has additional representations such as fullchildren which I am working on to be taken into consideration.

…ntations # Conflicts: # omod-1.8/pom.xml

…rsioning number, removed unnecessary comments

…e plugin

…ved all general Exception handling

mherman22

@capernix , have you seen the build failure. Can you investigate it?

...a/org/openmrs/module/webservices/rest/web/v1_0/resource/openmrs2_2/ConditionResource2_2.java

mherman22 · 2025-07-01T17:42:36Z

tools/openapi-generator-maven-plugin/src/main/java/org/openmrs/plugin/OpenAPIMojo.java

+import java.util.Map;
+
+@Mojo(name = "openapi", defaultPhase = LifecyclePhase.PROCESS_CLASSES, requiresDependencyResolution = ResolutionScope.RUNTIME)
+public class OpenAPIMojo extends AbstractMojo {


Suggested change

public class OpenAPIMojo extends AbstractMojo {

public class OpenmrsOpenApiSpecMojo extends AbstractMojo {

I think that name makes more sense

…e build cycle

mherman22 · 2025-07-01T18:32:41Z

tools/openapi-generator-maven-plugin/src/main/java/org/openmrs/plugin/OpenAPIMojo.java

+            return new URLClassLoader(urls.toArray(new URL[0]), Thread.currentThread().getContextClassLoader());
+
+        } catch (java.net.MalformedURLException e) {
+            throw new RuntimeException("Invalid URL in classpath elements: " + e.getMessage(), e);


shouldn't we prefer throwing MojoExecutionException or MojoFailureException for plugin errors, as Maven will display these more clearly?

capernix marked this pull request as draft May 20, 2025 17:16

mherman22 reviewed May 25, 2025

View reviewed changes

capernix force-pushed the RESTWS-980 branch from 066d0df to a5354f5 Compare June 18, 2025 07:03

capernix force-pushed the RESTWS-980 branch from a5354f5 to 55540c6 Compare June 18, 2025 07:43

mherman22 reviewed Jun 18, 2025

View reviewed changes

chibongho reviewed Jun 21, 2025

View reviewed changes

capernix added 9 commits July 1, 2025 22:23

Implemented a method to find all properties of a given resource

bdc387f

Added in tests to validate Schema Introspection

9dee07a

Added the feature of including properties from @PropertyGetter as well

b2f519f

Added a working Mojo Plugin

509bed8

Added javaparser PoC successfully

4919379

Enhanced the Plugin to invoke the required function and parse represe…

46662c4

…ntations # Conflicts: # omod-1.8/pom.xml

Adding logging with slf4j, improved indentation of Mojo, corrected ve…

578ecac

…rsioning number, removed unnecessary comments

Removed the Schema Introspector Functionality and phased it inside th…

a9dee67

…e plugin

Modified the error handling practices to be more descriptive and remo…

8cbf3f1

…ved all general Exception handling

capernix force-pushed the RESTWS-980 branch 2 times, most recently from 582488f to afd8d00 Compare July 1, 2025 17:16

Fixes for RESTWS-980 (Plugin, ConditionResource, etc.)

966ed50

capernix force-pushed the RESTWS-980 branch from afd8d00 to 966ed50 Compare July 1, 2025 17:20

mherman22 requested changes Jul 1, 2025

View reviewed changes

Moving the OpenAPI Plugin to the parent directory and adding it to th…

cc95ed5

…e build cycle

mherman22 reviewed Jul 2, 2025

View reviewed changes

Added OpenMRS repo information in the pom file

08a9287

	public class OpenAPIMojo extends AbstractMojo {
	public class OpenmrsOpenApiSpecMojo extends AbstractMojo {

RESTWS-980: Initial implementation of OpenAPI Generator Maven Plugin with JavaParser integration #657

Are you sure you want to change the base?

RESTWS-980: Initial implementation of OpenAPI Generator Maven Plugin with JavaParser integration #657

Uh oh!

Conversation

capernix commented May 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of what I changed

Key Implementation Details:

Issue I worked on

Checklist: I completed these to help reviewers :)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

capernix commented Jun 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mherman22 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

capernix commented May 20, 2025 •

edited

Loading